taler-docs

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

098-token-fountains.rst (12202B)


      1 .. _dd-98:
      2 
      3 DD 98: Token Fountains for Promotions
      4 #####################################
      5 
      6 :Design status: Draft
      7 :Implementation status: Partial
      8 :DD shepherd: TBD
      9 :Historical contributors: Bohdan Potuzhnyi
     10 :First published: 2026-07-23
     11 :Last substantive change: 2026-09-06
     12 :Normative references: ``core/api-merchant.rst`` (v43 token-fountain API)
     13 
     14 Summary
     15 =======
     16 
     17 This document proposes token fountains as a simple way for institutions to
     18 distribute promotional ``discount`` and ``subscription`` tokens.  A wallet
     19 imports a bearer credential, periodically retrieves the available grants and
     20 withdraws blind-signed tokens within limits configured by the institution.
     21 
     22 .. note::
     23 
     24   The merchant backend implements the fountain management and wallet APIs
     25   under protocol **v43** (commit ``97439d8f``), replacing the provisional
     26   ``vTokenFountains`` name.
     27 
     28 Motivation
     29 ==========
     30 
     31 Institutions sometimes want to distribute promotional benefits to a group
     32 without creating and paying a separate order for every recipient.  For
     33 example, a university may give students discount tokens accepted by a campus
     34 merchant, or periodically provide subscription tokens for a continuing
     35 promotion.
     36 
     37 GNU Taler already defines blind-signed merchant tokens.  What is missing is a
     38 simple distribution channel through which a wallet can obtain an authorized
     39 set of those tokens over time.  A **token fountain** is a bearer credential
     40 that authorizes such withdrawals.
     41 
     42 The institution can distribute a fountain as a QR code or deep link.  The
     43 wallet imports the link, learns which token families are available and
     44 withdraws blind-signed tokens subject to the configured limits.  Blind
     45 signatures keep a later use of a token unlinkable from its withdrawal.
     46 
     47 User Flow
     48 =========
     49 
     50 The recipient scans the promotion once.  The wallet obtains promotional
     51 tokens and offers an applicable token later at checkout.
     52 
     53 .. uml::
     54    :width: 90%
     55    :caption: Joining and using a token-fountain promotion
     56    :alt: Scan the promotion, receive promotional tokens in the wallet, use a
     57          token at checkout and receive the discount or benefit.
     58 
     59    @startuml
     60    left to right direction
     61 
     62    rectangle "Scan the\npromotion" as scan #d3deff
     63    rectangle "Wallet receives\npromotional tokens" as receive #d3deff
     64    rectangle "Use a token\nat checkout" as use #d3deff
     65    rectangle "Receive the\ndiscount or benefit" as benefit #d3deff
     66 
     67    scan --> receive
     68    receive --> use
     69    use --> benefit
     70    @enduml
     71 
     72 Requirements
     73 ============
     74 
     75 * Institutions must be able to distribute promotional tokens without
     76   creating a separate order for every withdrawal.
     77 
     78 * A fountain must support grants for existing ``discount`` and
     79   ``subscription`` token families.
     80 
     81 * Token withdrawals must use blind signatures so that later token use is not
     82   linkable to withdrawal.
     83 
     84 * The merchant backend must enforce per-period withdrawal limits atomically.
     85 
     86 * Wallets must be able to import a fountain using a QR code or Taler URI.
     87 
     88 * The bearer secret must not appear in HTTP request URLs after onboarding.
     89 
     90 * Deployments must be able to update or revoke future withdrawals without
     91   invalidating tokens that were already issued.
     92 
     93 Proposed Solution
     94 =================
     95 
     96 Terminology
     97 -----------
     98 
     99 In protocol descriptions, this document uses the existing token-family
    100 ``kind`` values:
    101 
    102 * A ``discount`` token is useful for a one-time or otherwise limited
    103   promotion.  It may be consumed without the merchant issuing a replacement.
    104 
    105 * A ``subscription`` token represents a continuing promotion.  When an order
    106   consumes it, the existing merchant token mechanism can return a replacement
    107   token envelope as an output of the selected choice.
    108 
    109 User-facing applications may call either benefit a **pass**.  The protocol
    110 continues to distinguish them by token-family kind.
    111 
    112 Fountain Credential
    113 -------------------
    114 
    115 A fountain has:
    116 
    117 * a public ``fountain_id`` identifying the fountain within a merchant
    118   instance;
    119 
    120 * a random ``fountain_secret`` used as its bearer credential;
    121 
    122 * a polling frequency; and
    123 
    124 * zero or more grants describing which token families may be withdrawn and
    125   at what rate.
    126 
    127 The onboarding URI is:
    128 
    129 ::
    130 
    131   taler://fountain/$MERCHANT_HOST[/$INSTANCE_PATH]/$FOUNTAIN_ID/$FOUNTAIN_SECRET
    132 
    133 The URI may be displayed as a QR code or opened as a wallet deep link.
    134 ``fountain_id`` tells the wallet which fountain it is importing, while
    135 ``fountain_secret`` authenticates the import.  The wallet must treat the full
    136 URI as sensitive.
    137 
    138 After import, the secret must not be placed in subsequent HTTP URLs.  It is
    139 sent in the ``Authorization`` header when reading fountain information and in
    140 the request body when withdrawing tokens, as specified by the merchant API.
    141 
    142 Deployment Models
    143 -----------------
    144 
    145 An institution may use one fountain for an entire campaign.  This is simple
    146 to distribute, but every recipient shares one bearer credential and the same
    147 withdrawal limits.  A leaked link cannot be revoked for only one recipient.
    148 
    149 Alternatively, the institution may create one fountain per recipient and
    150 distribute each link through its existing student communication system.  This
    151 allows independent limits and revocation without requiring the merchant
    152 backend to store the student's real identity.  The fountain description can
    153 contain an opaque reference meaningful only to the institution.
    154 
    155 The choice is operational rather than cryptographic.  Blind token issuance
    156 prevents the merchant from linking a withdrawn token to its later use in
    157 either model.
    158 
    159 Grant Model
    160 -----------
    161 
    162 Each :ts:type:`FountainGrant` names a token family and defines:
    163 
    164 * ``tokens_per_period_limit``, the maximum number of tokens signed for one
    165   issue-key validity period;
    166 
    167 * ``tokens_per_period_stash``, the number of tokens the wallet should try to
    168   keep available for that period; and
    169 
    170 * ``key_window_size``, the number of issue-key slots into the future for
    171   which the wallet may prepare tokens.
    172 
    173 The merchant may update grants without replacing the bearer credential.
    174 Wallets periodically retrieve the current grants according to ``poll_freq``.
    175 Removing a grant prevents future withdrawals from that family, but tokens
    176 already withdrawn remain valid according to the token family's issue keys.
    177 
    178 An empty grants array means no grants are currently available, not that the
    179 credential is revoked.  Wallets continue polling for updates.
    180 
    181 Protocol Flow
    182 -------------
    183 
    184 1. The institution configures suitable ``discount`` or ``subscription`` token
    185    families on the merchant backend.
    186 
    187 2. It creates a fountain with grants for those token families.
    188 
    189 3. The backend returns ``fountain_id`` and ``fountain_secret`` once.  The
    190    institution forms the Taler fountain URI and gives it to the intended
    191    recipients.
    192 
    193 4. A wallet imports the URI and calls ``GET /fountain/info`` using the bearer
    194    credential.
    195 
    196 5. The wallet prepares blinded token envelopes for any grants it needs to
    197    replenish and submits them to ``POST /fountain/withdraw``.
    198 
    199 6. The backend checks the grant, issue-key window and withdrawal limit, then
    200    blind-signs the accepted envelopes.
    201 
    202 7. The wallet unblinds and stores the tokens.  Their later use follows the
    203    existing merchant token protocol.
    204 
    205 Merchant API
    206 ------------
    207 
    208 Private Management Operations
    209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    210 
    211 The merchant API adds private operations to create, inspect, update, list and
    212 delete fountains:
    213 
    214 * ``POST /private/fountains``
    215 
    216 * ``GET /private/fountains`` (since protocol **v44**, paginated listing ordered
    217   by ``fountain_serial`` with ``limit``/``offset`` parameters; defaults to 20
    218   entries, with a hard cap of 100 per request)
    219 
    220 * ``GET /private/fountains/$FOUNTAIN_ID``
    221 
    222 * ``PATCH /private/fountains/$FOUNTAIN_ID``
    223 
    224 * ``DELETE /private/fountains/$FOUNTAIN_ID``
    225 
    226 Creation returns:
    227 
    228 .. ts:def:: FountainCreateResponse
    229 
    230   interface FountainCreateResponse {
    231     // Public identifier included in the wallet onboarding URI.
    232     fountain_id: Slug;
    233 
    234     // 256-bit bearer credential, Crockford Base32 encoded.
    235     // Returned only at creation; the backend stores only its hash.
    236     fountain_secret: string;
    237   }
    238 
    239 Wallet Operations
    240 ~~~~~~~~~~~~~~~~~
    241 
    242 ``GET /fountain/info`` returns the current grants, token-family metadata and
    243 issue public keys needed to prepare blinded envelopes.
    244 
    245 ``POST /fountain/withdraw`` accepts the bearer credential and blinded
    246 envelopes.  The request is grouped by token family and issue-key slot so that
    247 the backend can enforce each grant's limits.
    248 
    249 Each grant result returns ``token_sigs`` using the same
    250 :ts:type:`SignedTokenEnvelope` format as the order payment response.
    251 
    252 The backend records completed withdrawals by fountain and canonical request
    253 hash. Retrying with the same ``grants`` array returns the original result
    254 without consuming quota or signing again, even if the grants or key window
    255 have changed. Quota consumption, issued-token records and replay data are
    256 committed in one transaction so a failed operation does not consume quota.
    257 Replay data is retained as a complete response until the latest issue-key
    258 expiry in the withdrawal, even if some entries expire earlier.  Deleting a
    259 fountain drops its replay data at once.
    260 
    261 Deletion invalidates future requests using the credential.  It does not
    262 invalidate tokens that the wallet already withdrew.
    263 
    264 Security Considerations
    265 =======================
    266 
    267 Anyone possessing a fountain URI can withdraw under its grants.  Distribution
    268 systems must therefore protect the URI like any bearer credential.  Wallets
    269 must avoid exposing it in history, telemetry, screenshots or backups that are
    270 not intended to contain secrets.
    271 
    272 The backend stores only a hash of ``fountain_secret``.  Rate limiting of failed
    273 authentication may be handled by the deployment's reverse proxy.  The backend
    274 must enforce withdrawal limits atomically to prevent concurrent requests from
    275 exceeding a grant.
    276 
    277 Fountains are not proof of student identity.  Eligibility is decided by the
    278 institution when it distributes the link.  A shared campaign link can be
    279 forwarded, while a per-recipient link can only be individually disabled after
    280 the institution learns that it was compromised.
    281 
    282 Privacy Considerations
    283 ======================
    284 
    285 Fountain descriptions should contain opaque administrative references rather
    286 than names or student identifiers.  The merchant backend does not need a
    287 recipient's identity to issue blind-signed tokens.
    288 
    289 Network metadata can still correlate a wallet's requests.  Deployments that
    290 require stronger network-level privacy need an appropriate transport or proxy;
    291 blind signatures alone do not hide IP addresses or request timing.
    292 
    293 Drawbacks
    294 =========
    295 
    296 The fountain API adds persistent bearer credentials, polling and quota state
    297 to the merchant backend.
    298 
    299 Shared campaign fountains trade administrative simplicity for coarse
    300 revocation and shared quotas.  Per-recipient fountains provide better control
    301 but require the institution to create and distribute many distinct links.
    302 
    303 Test Plan
    304 =========
    305 
    306 * Test creation, inspection, update, listing and deletion of fountains.
    307 
    308 * Test importing a URI containing both ``fountain_id`` and
    309   ``fountain_secret``.
    310 
    311 * Test withdrawals for both ``discount`` and ``subscription`` token families.
    312 
    313 * Test atomic enforcement of per-period limits under concurrent requests.
    314 
    315 * Test rejection of unknown grants, unsupported issue-key slots and invalid
    316   credentials.
    317 
    318 * Test that deleting a fountain prevents new withdrawals without invalidating
    319   tokens already held by a wallet.
    320 
    321 * Test that token use cannot be linked to its fountain withdrawal from the
    322   blind-signature transcript.
    323 
    324 Definition of Done
    325 ==================
    326 
    327 * The merchant backend implements fountain management, information and
    328   withdrawal operations.
    329 
    330 * The onboarding URI includes the merchant location, ``fountain_id`` and
    331   ``fountain_secret``.
    332 
    333 * Wallet Core can import a fountain, poll its grants, replenish tokens within
    334   the configured limits and stop when the credential is revoked.
    335 
    336 * Merchant applications can create and distribute promotional fountains
    337   without supplying recipient identities to the merchant backend.
    338 
    339 * Discount and subscription token families retain their existing consumption
    340   and replacement semantics.