turnstile

README.md (9223B)

---

 # GNU Taler Turnstile
 
 A Drupal module that asks users to subscribe or pay using GNU Taler
 before granting access to nodes.
 
 Inspired by [Paivana](https://taler.net/) (DD 76), Turnstile uses
 *payment templates* in the merchant backend so that the paywall page
 itself is fully static and cacheable: no order is created when a
 visitor merely loads a paywalled article, and no PHP session is
 started for unauthenticated traffic. Orders only get created once a
 visitor's GNU Taler wallet actually picks the template up.
 
 
 ## Features
 
 - Adds a "price category" field to configurable content types
 - Static, cacheable paywall pages: bot traffic never creates orders
   in the merchant backend and never starts a PHP session
 - Access control without tracking — paid access is held in a
   short-lived HMAC cookie, no database table maps users to articles
 - Truncates node bodies to show teasers for visitors who did not (yet) pay
 - Server-side amount-check on every payment confirmation: the paid
   contract must match the price category configured for the
   fulfillment URL, otherwise the cookie is not minted
 - Configurable which content types are subject to access control
 - Subscription support with optional per-category discounts
 
 
 ## Installation
 
 1. Download and extract the module to your `modules/custom/` directory.
 2a. Enable the module via Drush: `drush en taler_turnstile`, or
 2b. Enable via the Drupal admin interface at `/admin/modules`.
 
 
 ## Configuration
 
 1. Navigate to `/admin/config/system/taler-turnstile` to configure:
 
 - **Enabled Content Types**: Select which content types should have
   the price field and access restriction.
 - **Payment Backend URL**: HTTP(S) URL of your Taler merchant backend
   (instance-specific URLs ending in `/instances/$ID/` are supported).
 - **Access Token**: Bearer token authenticating Turnstile to that
   merchant instance. The token must have the `templates-write` and
   `orders-read` permissions.
 - **Enable access if backend is down**: Fail-open toggle for the case
   where the merchant backend is not configured or unreachable.
 
 2. Make sure your Taler merchant backend is ready:
    - Bank account added
    - Legitimization with the payment service provider completed
 
 3. Configure one or more classes of subscriptions (optional). Navigate
    to `/admin/config/system/taler_turnstile/subscription-prices` and
    set the price at which each subscription token family can be
    purchased.
 
 The first time you save a working backend URL + token, Turnstile will
 push a `paivana`-style template for every existing price category
 into the merchant backend (template ID `turnstile-{category_id}`).
 You do not need to create those templates by hand.
 
 
 ## Usage
 
 1. Define one or more price categories under
    `/admin/structure/taler-turnstile-price-categories`:
    - Define a per-article price in each currency you accept.
    - Optionally define a discounted (or zero) price for each
      subscription class. A price of exactly `0` for a subscription
      marks the category as fully covered by that subscription —
      subscribers see the article for free.
 2. Create or edit a node of an enabled content type.
 3. Pick a price category in the new "Price category" field to gate
    the article behind a paywall.
 4. Earn money:
    - Visitors without a valid `taler_turnstile_paivana` cookie see
      the teaser plus a payment button.
    - Once their wallet has paid the merchant template, Turnstile
      mints the cookie and they see the full article.
 
 Editing a price category, adding/removing currencies, or changing the
 subscription prices automatically refreshes the matching templates in
 the merchant backend. Deleting a price category removes its template.
 
 
 ## How it Works
 
 The paywall is structured around three components:
 
 1. **Payment templates**, one per price category, kept in the
    merchant backend. Templates carry the v1 `choices` array that
    describes every accepted (currency, amount, optional subscription
    inputs/outputs) tuple. There is **no `website_regex`**: each node
    has its own fulfillment URL and templates are matched by category,
    not by URL pattern.
 
 2. **The paywall page** rendered by `hook_entity_view_alter()`. It
    replaces the full-mode build with a teaser plus a small
    `taler-turnstile-payment-container` block carrying the merchant
    URL, template ID, fulfillment URL, and a pre-built
    `taler://pay-template/...` URI. The same URI is also advertised
    as a `Paivana:` HTTP header for non-JS Taler clients. The page
    declares `cookies:taler_turnstile_paivana` as a cache context and
    `Vary: Cookie`, so it caches cleanly for everyone without the
    cookie (the dominant high-traffic case) while still serving the
    full content to visitors who do hold a cookie.
 
 3. **The confirmation endpoint** at `/taler-turnstile/paivana`. The
    client-side JavaScript:
    - Generates a 32-byte random `nonce` and computes
      `paivana_id = cur_time-base64url(SHA256(nonce || website || cur_time))`.
    - Renders `taler://pay-template/HOST/PATH/template_id?session_id={paivana_id}&fulfillment_url={website}`
      as a QR code and click-through link.
    - Long-polls `{merchant_backend}sessions/{paivana_id}?fulfillment_url=...`.
    - Once the merchant reports `paid`, POSTs `{order_id, nonce, cur_time, website}`
      back to `/taler-turnstile/paivana`. Turnstile reconstructs the
      paivana ID, looks up the order in the merchant backend, and
      **verifies that the paid `amount` matches one of the prices
      configured for the price category of the node behind `website`**.
      Only then does it mint the cookie and 303-redirect.
 
 Access for non-subscribers is held entirely in the cookie's HMAC
 (keyed on Drupal's per-site `private_key` and bound to client IP +
 fulfillment URL). Clearing cookies forgets paid access. There is no
 database table tracking who paid for what.
 
 If a contract bought a subscription token, the slug + expiration are
 also stored in the (now-started) PHP session so subsequent articles
 in the same subscription category short-circuit the paywall without
 needing a fresh payment.
 
 
 ## File Structure
 
 ```
 taler_turnstile/
 ├── config/
 │   ├── install/
 │   │   └── taler_turnstile.settings.yml - default configuration values
 │   └── schema/
 │       └── taler_turnstile.schema.yml - configuration schema (partial, without subscription prices)
 ├── js/
 │   ├── qrcode.min.js - QR code library from https://github.com/davidshimjs/qrcodejs
 │   └── payment-button.js - generates paivana_id, polls merchant /sessions, POSTs confirmation
 ├── src/
 │   ├── Controller/
 │   │   └── PaivanaController.php - handles POST /taler-turnstile/paivana, verifies amount, mints cookie
 │   ├── Entity/
 │   │   └── TurnstilePriceCategory.php - Price category config entity (also drives template lifecycle)
 │   ├── EventSubscriber/
 │   │   └── TurnstileConfigSubscriber.php - Reacts to config saves: field injection + template re-sync
 │   ├── Form/
 │   │   ├── PriceCategoryForm.php - Add/edit form handler
 │   │   ├── PriceCategoryDeleteForm.php - Delete confirmation form
 │   │   ├── SubscriptionPricesForm.php - Configure subscription prices
 │   │   └── TurnstileSettingsForm.php - Configure basics of Turnstile
 │   ├── PaivanaCookie.php - HMAC-SHA256 cookie service (keyed on Drupal's private_key)
 │   ├── PriceCategoryListBuilder.php - Admin list page builder
 │   ├── TalerMerchantApiService.php - Backend interaction: templates, order verification
 │   └── TurnstileFieldManager.php - Manages price-category field injection
 ├── templates/
 │   └── taler-turnstile-payment-button.html.twig - Paywall block markup + styles
 ├── taler_turnstile.libraries.yml - JS libraries and dependencies
 ├── taler_turnstile.info.yml - Module metadata and dependencies
 ├── taler_turnstile.install - Install/uninstall hooks
 ├── taler_turnstile.module - Hook implementations
 ├── taler_turnstile.permissions.yml - Permission definitions
 ├── taler_turnstile.routing.yml - Route definitions (admin pages + /taler-turnstile/paivana)
 ├── taler_turnstile.services.yml - Service container definitions
 ├── taler_turnstile.links.menu.yml - Menu link to Structure menu
 ├── taler_turnstile.links.action.yml - Action link for adding price categories
 └── README.md
 ```
 
 
 ## Requirements
 
 - Drupal 9 or 10
 - PHP 8.1 or higher (the module uses native enums)
 - A GNU Taler merchant backend supporting the v29 (or newer)
   `paivana` template type and the public `/sessions/$SESSION_ID`
   endpoint
 - The Drupal `path_alias` module (used by the confirmation endpoint
   to map fulfillment URLs back to nodes)
 
 
 ## License
 
 GPLv2-or-later, see COPYING for the full license terms.
 
 
 ## TODO
 
 - test subscriptions end-to-end through the new template flow
 - LATER: use order/template expiration from the merchant backend
   (with the v1.1 implementation) instead of hard-coding 1 day
 - LATER: rate-limit template instantiation on a per-IP basis as
   suggested by DD 76 (Solution B)