taler-android

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

expired-session-shows-a-protocol-error.md (3948B)


      1 # An expired session shows a protocol error instead of asking for credentials
      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 -- the terminal has the right behaviour implemented and it
      6 does not run. A cashier whose session has ended sees an error mentioning an
      7 `Authorization` header, and is left on a screen that cannot do anything.
      8 
      9 **Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/MainViewModel.kt`,
     10 the response-pipeline interceptor.
     11 
     12 **Found by:** `pos-simulator`, scenario `token_expires_while_idle`, using a
     13 75-second access token -- a credential the terminal cannot ask for itself,
     14 since the login form hard-codes `TokenDuration.Forever`.
     15 
     16 ## What happens
     17 
     18 Provision the terminal with a short-lived token, wait for it to expire, and
     19 refresh the order history. What should happen is the "Session expired – please
     20 re-enter your credentials" toast and a return to the login screen. What happens
     21 is a dialog:
     22 
     23 ```
     24 Error fetching the order history
     25 Error 2015 (401): The merchant refused the request due to lack of
     26 authorization. - Check credentials in 'Authorization' header
     27 OK
     28 ```
     29 
     30 and the terminal stays on the history screen, which can no longer load
     31 anything. The string is the backend's own hint, in English regardless of the
     32 app's language, and it names an HTTP header.
     33 
     34 ## Why
     35 
     36 The handling exists:
     37 
     38 ```kotlin
     39 // MainViewModel
     40 httpClient.responsePipeline.intercept(HttpResponsePipeline.Transform) { (info, body) ->
     41     if (context.response.status == HttpStatusCode.Unauthorized &&
     42         configManager.merchantConfig != null) {
     43         configManager.forgetPassword()
     44         configManager.notifySessionExpired()
     45     }
     46     proceedWith(subject)
     47 }
     48 ```
     49 
     50 and `MainActivity` observes `sessionExpired`, shows the toast and navigates to
     51 the configuration screen. The `session_expired_toast` string is translated into
     52 every language the app ships.
     53 
     54 It does not fire. The same client is built with `expectSuccess = true`
     55 (`createDefaultHttpClient`), which installs Ktor's default response validator;
     56 a 401 therefore raises `ClientRequestException` before the response pipeline's
     57 `Transform` phase runs, so the interceptor never sees the status. The exception
     58 is caught instead by `MerchantApi`'s `response { }` wrapper and surfaced as an
     59 ordinary failure string, which is what reaches the dialog.
     60 
     61 That it is caught there is not in doubt -- the message in the dialog is the
     62 backend's 401 body, which only `MerchantApi`'s error path formats.
     63 
     64 ## Reproducing it
     65 
     66 ```bash
     67 cd /tmp/taler-pos-sim/driver && . ../env.sh
     68 python3 suite.py token_expires_while_idle
     69 ```
     70 
     71 The scenario mints a 75-second token through the merchant API, provisions the
     72 terminal with it as a `taler-pos://` setup URI, waits it out and then asks the
     73 terminal to do something. `token_revoked_mid_payment` is the same question with
     74 the credential pulled at a moment of the harness's choosing.
     75 
     76 ## The fix
     77 
     78 The status has to be inspected somewhere the validator has not already thrown.
     79 Two options, neither of which is a one-liner, which is why no patch is
     80 attached:
     81 
     82 * **`HttpResponseValidator { handleResponseExceptionWithRequest { cause, _ -> … } }`**
     83   on the same client: the exception carries the response, so the 401 can be
     84   recognised there and `notifySessionExpired()` called before rethrowing. This
     85   keeps the single-place handling the current code was aiming at.
     86 * **In `MerchantApi`'s failure path**, which already distinguishes error
     87   shapes; it would have to be given a way to tell `ConfigManager`, which it
     88   currently has no reference to.
     89 
     90 Whichever is chosen, it is worth checking that it fires for every caller:
     91 `PaymentManager.checkPayment` deliberately swallows network errors to keep
     92 polling, so a session that ends while the payment screen is open must not end
     93 up silently retrying forever against a credential that no longer works.