taler-android

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

alias-registration-hardcodes-the-directory.md (6641B)


      1 <!--
      2   This file is part of GNU Taler
      3   (C) 2026 Taler Systems S.A.
      4 
      5   GNU Taler is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU General Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     12 
     13   You should have received a copy of the GNU General Public License along with
     14   GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 -->
     16 
     17 # Alias registration and contact lookup hard-code a production directory
     18 
     19 Found while trying to cover the `net.taler.wallet.contacts` package: its forms
     20 render and can be filled in (`AliasRegistrationScreen` is 60 % covered), but
     21 nothing past the "Register Alias" button can work against a test or
     22 self-hosted deployment, because the directory it talks to is a literal.
     23 
     24 **Severity: low** as a defect. The consequences are that a self-hosted Taler
     25 deployment cannot have its own directory, and that three wallet-core
     26 operations — `registerAlias`, `completeRegisterAlias`, `lookupAlias` — have no
     27 reachable success path, which is why `contacts` is the least covered package in
     28 the app (442 of its 827 instrumented lines missed).
     29 
     30 ## What happens
     31 
     32 The Taler directory (taldir) base URL is a literal in two places:
     33 
     34 ```kotlin
     35 // wallet/src/main/java/net/taler/wallet/contacts/AliasRegistrationScreen.kt:100
     36 val taldirBaseUri = "https://taldir.gnunet.org"
     37 ```
     38 
     39 ```kotlin
     40 // wallet/src/main/java/net/taler/wallet/contacts/ContactManager.kt:155,196,222
     41 taldirBaseUri: String = "https://taldir.gnunet.org",
     42 ```
     43 
     44 `ContactScreen.kt:244` calls `taldirLookupAlias(alias, aliasType)` without the
     45 parameter, so the default applies there too. Nothing in the app — not
     46 developer mode, not the settings screen, not a `taler://` URI — can change it:
     47 `grep -rn taldir wallet/src taler-kotlin-android/src` finds matches only inside
     48 `contacts/`, and there is no `BuildConfig` field, resource or preference for it.
     49 
     50 Every other service the wallet talks to is chosen at runtime: exchanges are
     51 added by URL in Settings, the merchant comes from the pay URI, the bank from
     52 the withdrawal URI, donau from its own settings screen.
     53 
     54 ## Why it matters
     55 
     56 1. **Nothing can exercise the second half of these screens.** The form renders
     57    and validates locally, but registering an alias or looking one up always
     58    goes to `taldir.gnunet.org`, so the simulator (and any CI, and any hand test
     59    on a device) either talks to a production service or gets an error. The
     60    challenge step, the completion step and every success state behind them stay
     61    unreachable, as do the operations that drive them.
     62 2. **A self-hosted Taler deployment cannot use it.** An operator who runs their
     63    own exchange, bank and directory still has their users' wallets registering
     64    aliases in GNUnet's directory.
     65 3. **In developer mode it is the one URL that stays remote.** Dev mode exists
     66    to point the wallet at a local stack; this screen ignores that.
     67 
     68 ## How it was established
     69 
     70 The two literals are the whole story on the app side:
     71 
     72 ```bash
     73 cd taler-android
     74 grep -rn 'taldir' --include=*.kt --include=*.xml wallet/src taler-kotlin-android/src
     75 ```
     76 
     77 ### And everything behind them works
     78 
     79 A real directory was then deployed beside the simulator's stack
     80 (`git://git.taler.net/taldir`, a Go service; see
     81 `simulator/backend/services/README.md`) and driven through wallet-core
     82 directly, which *does* take the base URL as a parameter:
     83 
     84 ```
     85 registerAlias         -> {}                      (202 Accepted)
     86   the validator recorded the challenge: J34V6DZG18X6EV0DFHQGDDGNJC
     87 completeRegisterAlias -> {}
     88 lookupAlias           -> {"targetUri": "http://127.0.0.1:11000/SIMADDRESS"}
     89 ```
     90 
     91 All three operations — the ones this campaign could never reach from the app —
     92 round-trip on the first attempt. So the feature is not unfinished and the
     93 protocol is not the problem: the app simply cannot be pointed at a directory.
     94 Everything from the "Register Alias" button onwards is unreachable for want of
     95 a URL field.
     96 
     97 ### And then through the app itself, with the URL untouched
     98 
     99 To be sure the operations were not just working *beside* the app, the emulator
    100 was made to answer for the hard-coded name — a hosts entry, the device's port
    101 443 forwarded to a TLS front end, and the front end's CA trusted by the
    102 simulator's own build type (`simulator/tls/README.md`). No URL in the app was
    103 changed. The shipped code path then ran end to end:
    104 
    105 ```
    106 POST taldir.gnunet.org/register/email        <- the "Register Alias" button
    107   the directory recorded: 285JEWK0894595KHSQSVYZW5E4
    108 POST taldir.gnunet.org/FAVWP84VPPY4…         <- the challenge, typed in
    109 GET  taldir.gnunet.org/FAVWP84VPPY4…         <- "Lookup with Taldir"
    110 ```
    111 
    112 and the screens followed it exactly as designed:
    113 
    114 ```
    115 the form:             ['email', 'Alias Type', 'Alias', '12', 'Duration (months)', 'Register Alias']
    116 after registering:    ['Challenge Solution', 'OK', 'Alias Registration']
    117 after completing:     ['Registration successful!', 'OK', 'Alias Registration']
    118 after the lookup:     ['Add Contact', 'Looked up', 'Petname', 'sim-w4-…@example.com',
    119                        'https://mailbox.gnunet.org/CFEF11D10YTNNM6G…', 'Mailbox', 'OK']
    120 ```
    121 
    122 Not one finding came out of it: register, challenge, complete and look up all
    123 work, and the lookup even fills the new contact's mailbox address in for the
    124 user. **The hard-coded URL is the only thing wrong with this feature**, and it
    125 is what keeps all of that out of reach of any test and any self-hosted
    126 deployment.
    127 
    128 (Two caveats from doing it: the deployed taldir's `/config` hard-codes
    129 protocol `0:0:0` while wallet-core's client declares `1:0:0` and refuses an
    130 incompatible server, so the version had to be patched locally before anything
    131 worked — see
    132 [`taldir-protocol-version-mismatch.md`](taldir-protocol-version-mismatch.md).
    133 And wallet-core resolved `localhost` to `::1` while the service listened on
    134 `127.0.0.1`, so the URL has to be numeric.)
    135 
    136 ## Suggested fix
    137 
    138 Give the directory the same treatment as donau: a `taldirBaseUrl` setting with
    139 `https://taldir.gnunet.org` as its default, read by `ContactManager` and passed
    140 down to `AliasRegistrationScreen`, and settable from the settings screen (or at
    141 least from developer mode). A `BuildConfig` field with the same default would
    142 already be enough to make the screens testable; a setting is what makes
    143 self-hosting work.