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.