taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

stack.py (20014B)


      1 # This file is part of GNU Taler
      2 # (C) 2026 Taler Systems S.A.
      3 #
      4 # GNU Taler is free software; you can redistribute it and/or modify it under the
      5 # terms of the GNU General Public License as published by the Free Software
      6 # Foundation; either version 3, or (at your option) any later version.
      7 #
      8 # GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
      9 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     10 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     11 #
     12 # You should have received a copy of the GNU General Public License along with
     13 # GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     14 """Host-side clients for the simulator's Taler stack.
     15 
     16 Everything the wallet's counterparties do happens here over HTTP: the bank
     17 (libeufin corebank) registers customers, opens and confirms withdrawals and
     18 reports balances; the merchant creates instances, orders and refunds.  Keeping
     19 the counterparties on the host makes a scenario deterministic — the only thing
     20 being explored is the wallet.
     21 """
     22 
     23 from __future__ import annotations
     24 
     25 import base64
     26 import json
     27 import os
     28 from pathlib import Path
     29 from urllib.parse import quote
     30 import uuid
     31 import urllib.error
     32 import urllib.request
     33 from dataclasses import dataclass
     34 from typing import Any, Optional
     35 
     36 DEFAULT_ENV = "/opt/taler-sim/run/stack/env.json"
     37 
     38 
     39 class HttpError(RuntimeError):
     40     def __init__(self, status: int, body: str, url: str):
     41         super().__init__(f"HTTP {status} for {url}: {body[:300]}")
     42         self.status = status
     43         self.body = body
     44 
     45 
     46 def _request(
     47     url: str,
     48     method: str = "GET",
     49     payload: Any = None,
     50     auth: Optional[tuple[str, str]] = None,
     51     timeout: int = 30,
     52 ) -> Any:
     53     data = None
     54     headers = {"Accept": "application/json"}
     55     if payload is not None:
     56         data = json.dumps(payload).encode()
     57         headers["Content-Type"] = "application/json"
     58     if auth:
     59         token = base64.b64encode(f"{auth[0]}:{auth[1]}".encode()).decode()
     60         headers["Authorization"] = f"Basic {token}"
     61     req = urllib.request.Request(url, data=data, headers=headers, method=method)
     62     try:
     63         with urllib.request.urlopen(req, timeout=timeout) as resp:
     64             body = resp.read().decode()
     65     except urllib.error.HTTPError as e:
     66         raise HttpError(e.code, e.read().decode(errors="replace"), url) from None
     67     if not body.strip():
     68         return None
     69     try:
     70         return json.loads(body)
     71     except json.JSONDecodeError:
     72         return body
     73 
     74 
     75 @dataclass
     76 class Env:
     77     """The URLs and credentials stack.sh wrote out."""
     78 
     79     exchange: str
     80     merchant: str
     81     bank: str
     82     donau: str
     83     auditor: str
     84     currency: str
     85     # Only there when backend/exchange2.sh is running beside the stack.
     86     exchange2: str | None = None
     87 
     88     @classmethod
     89     def load(cls, path: str = DEFAULT_ENV) -> "Env":
     90         with open(path) as f:
     91             d = json.load(f)
     92         return cls(
     93             exchange=d["exchange"], merchant=d["merchant"], bank=d["bank"],
     94             donau=d["donau"], auditor=d["auditor"], currency=d["currency"],
     95             exchange2=d.get("exchange2"),
     96         )
     97 
     98 
     99 class Bank:
    100     """libeufin-bank corebank API."""
    101 
    102     def __init__(self, base_url: str):
    103         self.base = base_url.rstrip("/")
    104 
    105     def config(self) -> Any:
    106         return _request(f"{self.base}/config")
    107 
    108     def register(self, username: str, password: str, name: str) -> Any:
    109         # Passwords shorter than 8 characters are rejected by the bank.
    110         return _request(f"{self.base}/accounts", "POST",
    111                         {"username": username, "password": password, "name": name})
    112 
    113     def account(self, username: str, password: str) -> Any:
    114         return _request(f"{self.base}/accounts/{username}", auth=(username, password))
    115 
    116     def balance(self, username: str, password: str) -> str:
    117         acc = self.account(username, password)
    118         bal = acc["balance"]
    119         sign = "-" if bal["credit_debit_indicator"] == "debit" else ""
    120         return f"{sign}{bal['amount']}"
    121 
    122     def payto(self, username: str, password: str) -> str:
    123         return self.account(username, password)["payto_uri"]
    124 
    125     def create_withdrawal(self, username: str, password: str, amount: str) -> Any:
    126         """Open a withdrawal operation; returns withdrawal_id + taler_withdraw_uri.
    127 
    128         A round spends more than the registration bonus, so an exhausted
    129         account is topped up and the request retried once rather than failing
    130         the scenario with something that looks like a wallet bug.
    131         """
    132         try:
    133             return _request(f"{self.base}/accounts/{username}/withdrawals", "POST",
    134                             {"amount": amount}, auth=(username, password))
    135         except HttpError as e:
    136             if e.status != 409 or "5102" not in e.body:
    137                 raise
    138             self.top_up(username, "EUR:2000")
    139             return _request(f"{self.base}/accounts/{username}/withdrawals", "POST",
    140                             {"amount": amount}, auth=(username, password))
    141 
    142     def withdrawal_status(self, wid: str) -> Any:
    143         return _request(f"{self.base}/withdrawals/{wid}")
    144 
    145     def confirm_withdrawal(self, username: str, password: str, wid: str) -> Any:
    146         """The step a human would take in the bank's own UI."""
    147         return _request(f"{self.base}/accounts/{username}/withdrawals/{wid}/confirm",
    148                         "POST", {}, auth=(username, password))
    149 
    150     def abort_withdrawal(self, username: str, password: str, wid: str) -> Any:
    151         return _request(f"{self.base}/accounts/{username}/withdrawals/{wid}/abort",
    152                         "POST", {}, auth=(username, password))
    153 
    154     ADMIN = ("admin", "secret-password")   # set by taler-unified-setup.sh
    155 
    156     def top_up(self, username: str, amount: str = "EUR:200") -> Any:
    157         """Credit a customer from the admin account.
    158 
    159         Scenario runs spend the registration bonus quickly, and an exhausted
    160         bank account looks just like a wallet bug in the logs, so accounts get
    161         topped up between iterations.  Admin may read any account, so the
    162         customer's own password is not needed.
    163         """
    164         account = _request(f"{self.base}/accounts/{username}", auth=self.ADMIN)
    165         payto = account["payto_uri"]
    166         joiner = "&" if "?" in payto else "?"
    167         return _request(
    168             f"{self.base}/accounts/{self.ADMIN[0]}/transactions", "POST",
    169             {"payto_uri": f"{payto}{joiner}amount={amount}&message=simulator top up"},
    170             auth=self.ADMIN,
    171         )
    172 
    173     def transfer(self, username: str, password: str, to_payto: str,
    174                  amount: str, subject: str) -> Any:
    175         """Pay from one customer account to any payto URI, with a subject.
    176 
    177         This is how a manual (not bank-integrated) withdrawal is completed: the
    178         wallet shows a subject -- the reserve public key -- and the user makes
    179         the transfer in their own bank. The exchange's wirewatch then sees the
    180         credit and the withdrawal goes through.
    181         """
    182         joiner = "&" if "?" in to_payto else "?"
    183         return _request(
    184             f"{self.base}/accounts/{username}/transactions", "POST",
    185             {"payto_uri": f"{to_payto}{joiner}amount={amount}"
    186                           f"&message={quote(subject)}"},
    187             auth=(username, password),
    188         )
    189 
    190     def transactions(self, username: str, password: str) -> Any:
    191         return _request(f"{self.base}/accounts/{username}/transactions",
    192                         auth=(username, password))
    193 
    194 
    195 class Merchant:
    196     """taler-merchant backend, private and management APIs."""
    197 
    198     def __init__(self, base_url: str, instance: str = "sim"):
    199         self.base = base_url.rstrip("/")
    200         self.instance = instance
    201 
    202     @property
    203     def private(self) -> str:
    204         return f"{self.base}/instances/{self.instance}/private"
    205 
    206     def config(self) -> Any:
    207         return _request(f"{self.base}/config")
    208 
    209     def exists(self) -> bool:
    210         try:
    211             _request(f"{self.base}/instances/{self.instance}/config")
    212             return True
    213         except HttpError:
    214             return False
    215 
    216     def create_instance(self, name: str = "Simulator Shop") -> None:
    217         """Idempotent.
    218 
    219         The management API is only open while the instance does not exist yet:
    220         a second POST for the same id is an update and comes back 401 (or 409),
    221         so an existing instance is probed for first and both codes tolerated.
    222         """
    223         if self.exists():
    224             return
    225         try:
    226             _request(f"{self.base}/management/instances", "POST", {
    227                 "id": self.instance,
    228                 "name": name,
    229                 "auth": {"method": "external"},
    230                 "address": {},
    231                 "jurisdiction": {},
    232                 "use_stefan": True,
    233                 "default_wire_transfer_delay": {"d_us": 3600 * 1000 * 1000},
    234                 "default_pay_delay": {"d_us": 3600 * 1000 * 1000},
    235             })
    236         except HttpError as e:
    237             if e.status not in (401, 409):
    238                 raise
    239 
    240     def add_account(self, payto_uri: str) -> Any:
    241         """Idempotent: re-adding the same account comes back 409."""
    242         try:
    243             return _request(f"{self.private}/accounts", "POST", {"payto_uri": payto_uri})
    244         except HttpError as e:
    245             if e.status != 409:
    246                 raise
    247             return None
    248 
    249     def create_otp_device(self, device_id: str = "simpos",
    250                           key: str = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
    251                           algorithm: str = "TOTP_WITHOUT_PRICE") -> Any:
    252         """A point-of-sale confirmation device.  Idempotent.
    253 
    254         An order that names one gets a `pos_confirmation` in its pay reply,
    255         which is the only thing that makes the wallet show its TOTP screen.
    256         The key is RFC 3548 base32, not Crockford.
    257         """
    258         body = {
    259             "otp_device_id": device_id,
    260             "otp_device_description": "Simulator point of sale",
    261             "otp_algorithm": algorithm,
    262             "otp_key": key,
    263             "otp_ctr": 0,
    264         }
    265         try:
    266             return _request(f"{self.private}/otp-devices", "POST", body)
    267         except HttpError as e:
    268             if e.status != 409:
    269                 raise
    270             return None
    271 
    272     def create_order(
    273         self,
    274         amount: str,
    275         summary: str = "Simulator order",
    276         fulfillment_url: str | None = None,
    277         otp_id: str | None = None,
    278         **order_extra: Any,
    279     ) -> dict:
    280         """Create an order and return it with its taler://pay URI.
    281 
    282         Each order gets its own fulfillment URL unless one is given: the
    283         wallet treats a second order with a fulfillment URL it has already
    284         paid for as a repurchase and answers "You've already paid for this
    285         purchase", which silently skips the payment a scenario was testing.
    286         """
    287         if fulfillment_url is None:
    288             fulfillment_url = (
    289                 "https://example.com/fulfillment/"
    290                 f"{uuid.uuid4().hex[:16]}"
    291             )
    292         order = {
    293             "amount": amount,
    294             "summary": summary,
    295             "fulfillment_url": fulfillment_url,
    296             **order_extra,
    297         }
    298         # otp_id is a sibling of "order", not a field of it.
    299         body: dict = {"order": order}
    300         if otp_id is not None:
    301             body["otp_id"] = otp_id
    302         res = _request(f"{self.private}/orders", "POST", body)
    303         status = self.order_status(res["order_id"], res.get("token"))
    304         return {
    305             "order_id": res["order_id"],
    306             "token": res.get("token"),
    307             "pay_uri": status.get("taler_pay_uri"),
    308             "status": status,
    309         }
    310 
    311     def create_token_family(self, slug: str = "simdiscount",
    312                             kind: str = "discount",
    313                             name: str = "Simulator discount") -> Any:
    314         """A token family, so orders can issue and demand tokens.
    315 
    316         Discount tokens are what the wallet shows under "Discounts"; nothing
    317         reaches that screen until an order issues one.
    318         """
    319         body = {
    320             "slug": slug,
    321             "name": name,
    322             "description": f"{kind} tokens issued by the simulator",
    323             "duration": {"d_us": 365 * 24 * 3600 * 1000 * 1000},
    324             "validity_granularity": {"d_us": 24 * 3600 * 1000 * 1000},
    325             "start_offset": {"d_us": 0},
    326             "kind": kind,
    327         }
    328         try:
    329             return _request(f"{self.private}/tokenfamilies", "POST", body)
    330         except HttpError as e:
    331             if e.status != 409:
    332                 raise
    333             return None
    334 
    335     def create_v1_order(self, choices: list[dict], summary: str = "Simulator v1 order",
    336                         fulfillment_url: str = "https://example.com/fulfillment",
    337                         **extra: Any) -> dict:
    338         """A version 1 ("mumimo") order: several choices, with token inputs
    339         and outputs."""
    340         order = {
    341             "version": 1,
    342             "summary": summary,
    343             "fulfillment_url": fulfillment_url,
    344             "choices": choices,
    345             **extra,
    346         }
    347         res = _request(f"{self.private}/orders", "POST", {"order": order})
    348         status = self.order_status(res["order_id"], res.get("token"))
    349         return {
    350             "order_id": res["order_id"],
    351             "token": res.get("token"),
    352             "pay_uri": status.get("taler_pay_uri"),
    353             "status": status,
    354         }
    355 
    356     @staticmethod
    357     def token_output(slug: str = "simdiscount", count: int = 1) -> dict:
    358         return {"type": "token", "token_family_slug": slug, "count": count,
    359                 "key_index": 0}
    360 
    361     @staticmethod
    362     def token_input(slug: str = "simdiscount", count: int = 1) -> dict:
    363         return {"type": "token", "token_family_slug": slug, "count": count}
    364 
    365     def create_template(self, template_id: str = "simtemplate",
    366                         amount: str = "EUR:1") -> Any:
    367         """A reusable order template, paid through a taler://pay-template URI."""
    368         body = {
    369             "template_id": template_id,
    370             "template_description": "Simulator template",
    371             "template_contract": {
    372                 "amount": amount,
    373                 "minimum_age": 0,
    374                 "pay_duration": {"d_us": 3600 * 1000 * 1000},
    375             },
    376         }
    377         try:
    378             return _request(f"{self.private}/templates", "POST", body)
    379         except HttpError as e:
    380             if e.status != 409:
    381                 raise
    382             return None
    383 
    384     def order_status(self, order_id: str, token: Optional[str] = None) -> Any:
    385         url = f"{self.private}/orders/{order_id}"
    386         if token:
    387             url += f"?token={token}"
    388         return _request(url)
    389 
    390     def refund(self, order_id: str, amount: str, reason: str = "simulator refund") -> Any:
    391         return _request(f"{self.private}/orders/{order_id}/refund", "POST",
    392                         {"refund": amount, "reason": reason})
    393 
    394     def delete_order(self, order_id: str) -> Any:
    395         return _request(f"{self.private}/orders/{order_id}", "DELETE")
    396 
    397 
    398 CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
    399 
    400 
    401 def encode_crock(data: bytes) -> str:
    402     """The base32 Taler uses for hashes and keys (GNUNET_STRINGS_data_to_string).
    403 
    404     Crockford's alphabet, big-endian bit order, no padding.  Verified against
    405     the exchange's own signing keys: the hex in `exchange.exchange_sign_keys`
    406     encodes to exactly the strings /keys publishes.
    407     """
    408     out = []
    409     bits = vbit = rpos = 0
    410     while rpos < len(data) or vbit > 0:
    411         if rpos < len(data) and vbit < 5:
    412             bits = (bits << 8) | data[rpos]
    413             rpos += 1
    414             vbit += 8
    415         if vbit < 5:
    416             bits <<= (5 - vbit)
    417             vbit = 5
    418         out.append(CROCKFORD[(bits >> (vbit - 5)) & 31])
    419         vbit -= 5
    420     return "".join(out)
    421 
    422 
    423 def revoke_denomination(denom_pub_hash: bytes | str,
    424                         conf: str = "sim.conf",
    425                         run_dir: str = "/opt/taler-sim/run/stack") -> str:
    426     """Revoke a denomination key, as an exchange operator would.
    427 
    428     Destructive and stack-wide: the denomination stays revoked until the stack
    429     is started again, and every wallet holding one of its coins has to recoup.
    430     """
    431     import subprocess
    432     crock = (denom_pub_hash if isinstance(denom_pub_hash, str)
    433              else encode_crock(denom_pub_hash))
    434     proc = subprocess.run(
    435         ["taler-exchange-offline", "-c", conf,
    436          "revoke-denomination", crock, "upload"],
    437         cwd=run_dir, capture_output=True, text=True, timeout=120,
    438     )
    439     if proc.returncode != 0:
    440         raise RuntimeError(f"revoking {crock} failed: "
    441                            f"{(proc.stderr or proc.stdout).strip()[:300]}")
    442     return crock
    443 
    444 
    445 def provision(env: Optional[Env] = None,
    446               # Seven, not five: the harness has AVDs for workers 0..6 and
    447               # worker 6 (the version matrix) banks as wallet7.  A plain
    448               # `python3 stack.py` used to leave that account out, and every
    449               # scenario on that worker then died with
    450               # `HTTP 401 ... accounts/wallet7 ... Unknown account` -- which
    451               # looked exactly like a platform failure in the matrix.
    452               workers: int = int(os.environ.get("SIM_WORKERS", "7"))) -> dict:
    453     """Make the stack usable by a wallet: one merchant instance with a bank
    454     account, and one bank customer per parallel worker."""
    455     env = env or Env.load()
    456     bank, merchant = Bank(env.bank), Merchant(env.merchant)
    457     out: dict[str, Any] = {"currency": env.currency}
    458     # A stack start wipes the exchange database, so its master key is new while
    459     # the peer wallets still remember the old one and refuse to talk to it
    460     # ("the exchange changed its master public key", code 7066).  Provisioning
    461     # runs right after every stack start, which is exactly when they should be
    462     # thrown away.
    463     out["cli_wallets_removed"] = sorted(
    464         p.name for p in Path("/opt/taler-sim/run").glob("cli-wallet-*.sqlite3*")
    465     )
    466     for stale in Path("/opt/taler-sim/run").glob("cli-wallet-*.sqlite3*"):
    467         stale.unlink(missing_ok=True)
    468     accounts = [("merchant", "merchantpass1", "Simulator Shop")]
    469     accounts += [(f"wallet{i + 1}", f"walletpass{i + 1}", f"Wallet {i + 1}")
    470                  for i in range(workers)]
    471     # One more per worker for the taler-wallet-cli peer wallet.
    472     accounts += [(f"peer{i + 1}", f"peerpass{i + 1}", f"Peer {i + 1}")
    473                  for i in range(workers)]
    474     for user, password, name in accounts:
    475         try:
    476             bank.register(user, password, name)
    477             out[f"{user}_registered"] = True
    478         except HttpError as e:
    479             # 409 means the account survived from an earlier run.
    480             if e.status != 409:
    481                 raise
    482             out[f"{user}_registered"] = False
    483     # Keep every account well above what one round can spend: ~75 scenarios
    484     # share these accounts, and a fresh one holds only the EUR:100
    485     # registration bonus.
    486     for user, password, _ in accounts[1:]:
    487         try:
    488             balance = bank.balance(user, password)
    489             value = float(balance.split(":")[1])
    490             if value < 1000:
    491                 bank.top_up(user, "EUR:2000")
    492                 out[f"{user}_topped_up"] = True
    493         except (HttpError, ValueError, IndexError) as e:
    494             out[f"{user}_top_up_error"] = str(e)[:120]
    495     merchant.create_instance()
    496     merchant.add_account(bank.payto("merchant", "merchantpass1"))
    497     out["merchant_instance"] = merchant.instance
    498     out["balances"] = {
    499         f"wallet{i + 1}": bank.balance(f"wallet{i + 1}", f"walletpass{i + 1}")
    500         for i in range(workers)
    501     }
    502     return out
    503 
    504 
    505 if __name__ == "__main__":
    506     import sys
    507     e = Env.load(sys.argv[1] if len(sys.argv) > 1 else DEFAULT_ENV)
    508     print(json.dumps(provision(e), indent=2))