taler-android

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

setup-uri-drops-the-port.md (2983B)


      1 # A `taler-pos://` setup URI loses the backend's port
      2 
      3 > **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
      4 
      5 **Severity:** medium -- a merchant whose backend does not listen on 443 cannot
      6 provision a terminal by QR code at all. The terminal silently configures itself
      7 for the wrong address and then reports a connection error, which looks like the
      8 backend being down.
      9 
     10 **Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/MainActivity.kt`,
     11 `handleSetupIntent`.
     12 
     13 **Found by:** `pos-simulator`, scenario `provision_port_is_dropped`.
     14 
     15 ## What happens
     16 
     17 Deliver a setup URI that names a port:
     18 
     19 ```
     20 taler-pos://backend.demo.taler.net:443/instances/sandbox#secret-token:...
     21 ```
     22 
     23 The terminal configures itself for
     24 
     25 ```
     26 https://backend.demo.taler.net/instances/sandbox
     27 ```
     28 
     29 The port is gone. With `:443` that is harmless, because 443 is what https means
     30 anyway -- which is exactly why it is easy to miss. With any other port the
     31 terminal is now pointed somewhere else entirely.
     32 
     33 ## Why
     34 
     35 ```kotlin
     36 val host = data.host ?: return
     37 ...
     38 val merchantUrl = Uri.Builder()
     39     .scheme("https")
     40     .encodedAuthority(host)
     41     .appendPath("instances")
     42     .appendPath(instance)
     43     .build()
     44     .toString()
     45 ```
     46 
     47 `Uri.getHost()` returns the host *without* the port; the authority is
     48 `getAuthority()` (or `getHost()` plus `getPort()`). So `encodedAuthority(host)`
     49 rebuilds the URL with the port dropped.
     50 
     51 The login form does not have this problem -- `sanitizeMerchantUrlAndUpdateFields`
     52 keeps the port explicitly:
     53 
     54 ```kotlin
     55 val port = if (uri.port != -1) ":${uri.port}" else ""
     56 val baseHost = "$host$port"
     57 ```
     58 
     59 so the two provisioning paths disagree about the same input. That is also why
     60 the simulator's mock-backend scenarios provision through the form: a mock on
     61 `localhost:19443` is unreachable through a setup URI.
     62 
     63 ## Reproducing it
     64 
     65 ```bash
     66 cd /tmp/taler-pos-sim/driver && . ../env.sh
     67 python3 suite.py provision_port_is_dropped
     68 ```
     69 
     70 Or by hand: `adb shell am start -a android.intent.action.VIEW -d
     71 'taler-pos://your-host:8443/instances/x#your-token'` and read the merchant URL
     72 back off the Settings screen's About block.
     73 
     74 ## The fix
     75 
     76 `encodedAuthority(data.encodedAuthority)` instead of
     77 `encodedAuthority(host)` -- `data` is the `taler-pos://` URI and its authority
     78 is exactly the `host:port` the back office put in the QR code. (`host` is still
     79 needed above it for the `return` that rejects a URI with no host at all.)
     80 
     81 Worth checking at the same time: the scheme is hard-coded to `https`, so a
     82 backend reachable only over http cannot be provisioned either way. That is a
     83 defensible policy for a payment terminal, but it is a policy rather than an
     84 oversight, and it is the reason the simulator's own mock backend has to answer
     85 TLS.
     86 
     87 No patch: a one-line change, but which spelling is wanted depends on whether a
     88 non-default port is meant to be supported at all, which is a decision rather
     89 than a bug fix.