taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

commit e7d7657c5eabc47aeac23fd5f10553d27538fc59
parent 0006a4c39af131ae52171f73f0b2d209045a03d6
Author: Florian Dold <dold@taler.net>
Date:   Thu, 19 Nov 2026 19:14:51 +0100

Paivana: specify the session timestamp as the minimum cookie expiry

Diffstat:
Mcore/wallet-core/payments/prepare-pay-for-paivana.rst | 3+--
Mdesign-documents/076-paywall-proxy.rst | 118+++++++++++++++++++++++++++++++++++--------------------------------------------
Mfrags/drupal-paivana-manual.rst | 15+++++----------
Mfrags/paivana-httpd-manual.rst | 14+++++++-------
Mfrags/wordpress-paivana-manual.rst | 13+++++--------
Mwallet/wallet-core.md | 2+-
6 files changed, 71 insertions(+), 94 deletions(-)

diff --git a/core/wallet-core/payments/prepare-pay-for-paivana.rst b/core/wallet-core/payments/prepare-pay-for-paivana.rst @@ -65,7 +65,6 @@ // Crockford-base32 encoded 16-byte client nonce. nonce: string; - // End of the access period used to derive the Paivana - // session ID. + // Minimum acceptable access expiry bound into the Paivana session ID. expiration: TalerProtocolTimestamp; } diff --git a/design-documents/076-paywall-proxy.rst b/design-documents/076-paywall-proxy.rst @@ -6,7 +6,7 @@ DD 76: Paivana - Fighting AI Bots with GNU Taler :DD shepherd: TBD :Historical contributors: Florian Dold, Christian Grothoff :First published: 2025-11-26 -:Last substantive change: 2026-08-07 +:Last substantive change: 2026-11-19 :Implementation evidence: ``merchant`` (2026-01-20; 2026-04-25; 2026-04-27; 2026-08-04); ``paivana`` (2026-04-19) :Normative references: ``taler-paivana-manual.rst``, ``frags/paivana-httpd-manual.rst``, and ``core/api-merchant.rst`` @@ -57,17 +57,13 @@ Steps: this client IP address and ``{website}`` at this time. The *Paivana Cookie* is computed as: - ``expiration || '-' || crock32(HKDF(salt=expiration, ikm=paivana_server_secret, info=website || '\0' || client_ip))``. - - where ``expiration`` in the prefix is the expiration time for the - cookie (and thus the access to the article) in seconds - (to keep it short) while in the salt it is the binary GNUnet - absolute time (microseconds) in network byte order. - Note that this value is the *end of the access being sold*, chosen by - the client and capped by the contract; it is not a statement about - when anything happened, and in particular it is not the client's idea - of the current time. (It was called ``cur_time`` in earlier drafts of - this document, which invited exactly that misreading.) + ``cookie_expiration_str || '-' || crock32(HKDF(salt=cookie_expiration_enc, ikm=paivana_server_secret, info=website || '\0' || client_ip))``. + + The cookie may expire at or after the ``min_expiration`` in the + ``paivana_id``, up to the paid contract's ``max_pickup_time``. + ``cookie_expiration_str`` encodes that instant as decimal ASCII seconds + since the Epoch. The HKDF salt ``cookie_expiration_enc`` encodes the + same instant as an unsigned 64-bit big-endian count of microseconds. ``HKDF`` is GNUnet's HKDF (``GNUNET_CRYPTO_hkdf_gnunet()``, which extracts with HMAC-SHA-512 and expands with HMAC-SHA-256), and the output is 512 bits. @@ -100,33 +96,22 @@ Steps: the ``taler://pay-template/`` URL minus the client-computed ``{paivana_id}`` and fullfillment URL (see below). -* The browser (rendering the paywall page) generates a random - *paivana ID* via JS using the end of the access it intends to buy - (``expiration``) in seconds since the Epoch and the current URL - (``{website}``) plus some freshly generated entropy (``{nonce}``): - - ``paivana_id := expiration || '-' || b64url(SHA256(nonce || website || '\0' || expiration))``. - - The exact byte string that is hashed is the concatenation of: +* The paywall page chooses the minimum acceptable access expiry and generates + a fresh random 16-byte ``nonce`` for the article URL ``website``. - * the 16-byte (128-bit) binary ``nonce``; - * the UTF-8 encoding of ``website``, including its terminating - zero byte (which separates it unambiguously from the timestamp); - * ``expiration`` as an 8-byte **big-endian (network byte order) - number of microseconds** since the Epoch, that is, the value of - the seconds-based ``expiration`` multiplied by 1000000. + ``paivana_id := min_expiration_str || '-' || b64url(SHA256(nonce || website || '\0' || min_expiration_enc))``. - Note that ``expiration`` thus appears twice in two different - encodings: the ``paivana_id`` *prefix* is the timestamp in - **seconds** (as decimal ASCII, to keep the identifier short), - while the hashed value is the same instant in **microseconds** - in network byte order. + ``min_expiration_str`` is the minimum expiry in decimal ASCII seconds since + the Epoch. ``min_expiration_enc`` encodes the same instant as an unsigned + 64-bit big-endian count of microseconds (seconds multiplied by 1000000). + The hash covers the binary nonce, the UTF-8 URL with its terminating zero + byte, and the eight timestamp bytes, in that order. - The client is free to pick this value — it is asking for access until - a particular moment, and it is the contract's ``max_pickup_time`` that - decides whether it may have it. Since the same value goes into the - session ID the order is created under, it cannot be revised after the - fact. + The paywall chooses how much remaining access to request. For example, a + page opened at 12:50 can ask for one hour by setting the minimum to 13:50. + A new purchase must be able to cover that minimum. The template's pickup + duration describes the access a new order buys. A paywall can ask for a + shorter period so a reader can reuse part of an earlier purchase. Here ``b64url`` is the RFC 7515 base64 URL encoder without padding, used to keep the result short (same reason for the use of @@ -139,6 +124,9 @@ Steps: ``taler://pay-template/{merchant_backend}/{template_id}?session_id={paivana_id}&fulfillment_url={website}`` URI is generated and rendered as a QR code and link, prompting the user to pay for access to the ``{website}`` using GNU Taler. + The page can retire its QR code and link after a local timeout and let the + reader request a fresh offer. This timeout is local to the page. A payment + already confirmed can still be redeemed while its contract grants access. * The JavaScript in the paywall page running in the browser (or the non-JS client) long-polls @@ -150,8 +138,8 @@ Steps: to the order creation (the session ID here will work just like existing use of ``session_ids`` in session-bound payments). Similarly, the ``{website}`` works as the fulfillment URL as usual. -* The wallet then must pay for the resulting order - by talking to the Merchant backend. +* The wallet replays a qualifying paid order under the new session ID, or + asks the reader to confirm a new purchase. * When the long-poller returns and the payment has succeeded, the browser (still rendering the paywall page) also learns the order ID. * The JavaScript of the paywall page (or the non-JS client @@ -159,9 +147,9 @@ Steps: ``nonce``, ``expiration`` and ``website`` to ``{domain}/.well-known/paivana``. In this JSON request, the ``nonce`` is ``crock32``-encoded and - ``expiration`` is a normal GNU Taler timestamp object - (``{"t_s": ...}``, in seconds); the server re-derives the binary - inputs given above from these values. + the JSON member ``expiration`` carries the minimum used in the ID as a + GNU Taler timestamp (``{"t_s": ...}``, in seconds). The proxy uses those + values to reconstruct the hash inputs. Note that by the time this POST is made, the client already has the merchant backend's word that the order was paid: that is precisely @@ -188,27 +176,24 @@ Steps: posted ``website``; if it has none, the ``website`` must lie under paivana-httpd's own configured base URL, so that the client cannot choose which site it is admitted to; - * ``expiration`` is not later than the contract's ``max_pickup_time``, - which is what stops a client from buying five minutes of access and - minting itself a cookie valid for a year. - - For repeat visits, the wallet may replay an earlier paid order only if - its access window is still open and its ``max_pickup_time`` covers the - session's requested ``expiration``. An absent or ``never`` deadline is - unlimited. A repeat visit does not extend the paid access period. - - When the wallet itself constructs the Paivana session, it can reuse - remaining access by capping ``expiration`` at the earlier order's - ``max_pickup_time`` **before** computing the session ID. The same capped - expiration must be used when redeeming the order for a cookie. A session - constructed by a browser already binds the expiration and nonce; the - wallet cannot change that expiration. If the previous order cannot cover - it, the wallet offers a new purchase requiring confirmation. After the - old access window expires, a new purchase is required in either flow. - - If so, paivana-httpd issues the Paivana cookie described above, with - ``Max-Age`` derived from ``expiration``, and redirects to the - ``{website}``. + * the contract's ``max_pickup_time`` is strictly in the future and is at + least the requested minimum. An absent or ``never`` deadline grants + unlimited access. + + The wallet applies the same deadline checks when selecting a paid order + for this merchant and article. An order that still grants access satisfies + a minimum in the past. For example, at 12:50 an order valid until 13:00 + covers a minimum of 13:00, even in a browser with empty storage. + Scanning the fresh QR associates the paid order with the browser's new + session. A minimum of 13:15 requires a different qualifying order or + confirmation of a new purchase. The wallet cannot revise the minimum in + a scanned QR. A wallet constructing its own session can choose the minimum + after inspecting the reader's purchases. + + The proxy issues the cookie with ``Max-Age`` computed from the actual + cookie expiry and redirects to the article. For example, an order valid + until 13:00 can yield a cookie expiring at 13:00 when the page requested + a minimum of 12:55. This query is made as a **long poll with a short, fixed bound** (5 seconds in the current implementation). Both halves matter: @@ -301,15 +286,16 @@ order or a paivana ID has already been redeemed. The cookie it returns is bound to the address of whoever posted the redemption, not to the address that paid. Anyone holding the four posted fields — order ID, ``nonce``, ``expiration`` and ``website`` — can therefore obtain their own cookie, for -their own address, at any point until ``expiration``, and a buyer who -publishes those four fields has given the article to everyone who reads -them. +their own address, while the merchant confirms payment under that session +and the contract still grants access. Replaying the order under a fresh +session can supersede the old session at the merchant. Cookies already +issued remain valid through their own expiry. This is intended behaviour and not a defect. What is sold is access to one resource until one moment, and the buyer may pass that on, in the same way and for the same reasons that the buyer of a newspaper may hand it to the next reader. The purchase stays bounded by what was bought: sharing extends -a payment to more readers, never to more URLs and never past ``expiration``, +a payment to more readers, never to more URLs and never past the paid contract’s deadline, so a client that wants the whole site still pays for the whole site. That bound is what lets the design's actual goal — making bulk automated retrieval expensive — survive the sharing. **The risk is accepted on the diff --git a/frags/drupal-paivana-manual.rst b/frags/drupal-paivana-manual.rst @@ -451,16 +451,11 @@ and 303-redirect the browser back to the article. .. note:: - The field named ``cur_time`` here is not a current time: it is - the *expiration* of the access being bought, which is why it is - also one of the inputs hashed into the ``paivana_id``. - ``paivana-httpd`` and - :doc:`DD 76 </design-documents/076-paywall-proxy>` have renamed - it to ``expiration`` for exactly that reason. **TODO:** rename - it here too, in the module's JavaScript and controller and then - in this manual; until the module changes, this document - deliberately keeps the old name so that it matches the code that - is shipped. + The module calls the timestamp hashed into ``paivana_id`` ``cur_time``. + In :doc:`DD 76 </design-documents/076-paywall-proxy>`, this timestamp + is the minimum acceptable cookie expiry. The cookie may expire later. + ``paivana-httpd`` calls this field ``expiration`` in its redemption request. + **TODO:** Adopt that field name in the module's JavaScript and controller. The cookie is keyed on Drupal's per-site ``private_key``, bound to the visitor's client IP and to the specific fulfillment URL, diff --git a/frags/paivana-httpd-manual.rst b/frags/paivana-httpd-manual.rst @@ -515,8 +515,8 @@ 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 +The cookie expires at the paid order's ``max_pickup_time``. Configure +``max_pickup_duration`` on the template 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 @@ -560,8 +560,9 @@ 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. +``BASE_URL``), and the order must still grant access. Its ``max_pickup_time`` +must cover the minimum in the request's ``expiration`` field. The proxy +issues the cookie through the paid order's deadline. 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 @@ -585,9 +586,8 @@ Status Meaning 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. +410 The order's ``max_pickup_time`` has passed or is earlier + than the minimum access expiry in the request. 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 diff --git a/frags/wordpress-paivana-manual.rst b/frags/wordpress-paivana-manual.rst @@ -445,14 +445,11 @@ cookie and instruct the browser to reload the article. .. note:: - The field named ``cur_time`` here is not a current time: it is the - *expiration* of the access being bought, which is why it is also one of - the inputs hashed into the ``paivana_id``. ``paivana-httpd`` and - :doc:`DD 76 </design-documents/076-paywall-proxy>` have renamed it to - ``expiration`` for exactly that reason. **TODO:** rename it here too, in - the plugin's JavaScript and REST controller and then in this manual; - until the plugin changes, this document deliberately keeps the old name - so that it matches the code that is shipped. + The plugin calls the timestamp hashed into ``paivana_id`` ``cur_time``. + In :doc:`DD 76 </design-documents/076-paywall-proxy>`, this timestamp + is the minimum acceptable cookie expiry. The cookie may expire later. + ``paivana-httpd`` calls this field ``expiration`` in its redemption request. + **TODO:** Adopt that field name in the plugin's JavaScript and controller. The cookie is keyed on Wordpress' built-in ``wp_salt('auth')``, bound to the visitor's ``REMOTE_ADDR`` and ``Path``-scoped to the specific fulfillment URL, diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md @@ -6886,7 +6886,7 @@ export interface PaivanaRedemption { url: string; /** Crockford-base32 encoded 16-byte client nonce. */ nonce: string; - /** End of the access period used to derive the Paivana session ID. */ + /** Minimum acceptable access expiry bound into the Paivana session ID. */ expiration: TalerProtocolTimestamp; } ```