pos-config-url-percent-encodes-the-separator.md (3683B)
1 # The terminal asks for its configuration at `/private%2Fpos` 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 -- works against a bare merchant backend, and cannot work 6 behind a reverse proxy that does not decode encoded slashes, which is the 7 default for Apache and a common hardening setting for nginx. The terminal then 8 cannot be configured at all, and says only "Error: Could not connect to 9 configuration server". 10 11 **Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigManager.kt:340` 12 13 **Found by:** `pos-simulator`, scenario `pos_config_url_encodes_the_separator`. 14 15 ## What happens 16 17 The request the terminal makes for its point-of-sale configuration arrives with 18 the path separator percent-encoded. From the mock backend's request log, with 19 the terminal configured for instance `mockshop`: 20 21 ``` 22 POST /instances/mockshop/private/token 200 23 GET /instances/mockshop/private%2Fpos <- the configuration request 24 GET /instances/mockshop/config 200 25 GET /instances/mockshop/private/products/pretzel 200 26 ``` 27 28 Only that one request is affected. Every other call -- the token, the backend 29 config, the products, the orders, the refunds -- goes through 30 `MerchantConfig.urlFor`, which concatenates strings and so leaves the separator 31 alone. 32 33 ## Why 34 35 ```kotlin 36 val url = when (val c = config) { 37 is Config.New -> c.merchantUrl.toUri() 38 .buildUpon() 39 .appendPath("private/pos") // ConfigManager.kt:340 40 .build() 41 .toString() 42 } 43 ``` 44 45 `Uri.Builder.appendPath` appends **one path segment** and percent-encodes 46 anything in it that is not legal inside a segment -- including `/`, because a 47 segment may legitimately contain an encoded slash. The intent was two segments. 48 49 ## Why nobody has noticed 50 51 The GNU Taler merchant backend decodes the request path before routing, so it 52 answers the encoded form identically: 53 54 ``` 55 $ curl -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOK" \ 56 'https://backend.demo.taler.net/instances/sandbox/private%2Fpos' 57 200 58 $ curl -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOK" \ 59 'https://backend.demo.taler.net/instances/sandbox/private/pos' 60 200 61 ``` 62 63 A deployment that puts the backend behind a reverse proxy need not. Apache's 64 `AllowEncodedSlashes` defaults to `Off` and answers 404 for such a request 65 before it ever reaches the backend; nginx normalises or rejects depending on 66 whether the location uses a rewrite. This is the mock backend's exact-match 67 routing answering 404 that first surfaced it -- a mock is stricter than the 68 real thing on purpose, and that is the value of having one. 69 70 ## Reproducing it 71 72 ```bash 73 cd /tmp/taler-pos-sim/driver && . ../env.sh 74 python3 ../findings/repro_encoded_path_separator.py 75 ``` 76 77 It starts a mock backend that records the paths it is asked for, provisions the 78 terminal against it through the login form, and prints every request that 79 arrived with an encoded separator. 80 81 ## The fix 82 83 One line; `pos-config-url-percent-encodes-the-separator.diff` has it. Either 84 append the two segments separately: 85 86 ```kotlin 87 .appendPath("private") 88 .appendPath("pos") 89 ``` 90 91 or, matching what the rest of the module does, use `MerchantConfig.urlFor` -- 92 but that needs a `MerchantConfig`, which does not exist yet at this point in 93 `fetchConfig`, so the two `appendPath` calls are the smaller change. 94 95 `appendEncodedPath("private/pos")` also works and is what the name suggests, 96 but it is the riskier spelling: it would pass a merchant-supplied segment 97 through unencoded if the string ever stopped being a literal.