commit c04119f0ae3428bed3a76c99622f746419c3e939
parent 44e4d30aaa7d3326beb812c934440aa699d00dcd
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 24 Sep 2026 00:25:02 +0200
exchange: document the process-bound OAuth2 state of /kyc-proof
Issue: https://bugs.taler.net/n/11740
Signed-off-by: Christian Grothoff <christian@grothoff.org>
Diffstat:
2 files changed, 28 insertions(+), 1 deletion(-)
diff --git a/core/exchange/get-kyc-proof-PROVIDER_NAME.rst b/core/exchange/get-kyc-proof-PROVIDER_NAME.rst
@@ -32,7 +32,11 @@
:query code=CODE:
OAuth 2.0 code argument.
:query state=STATE:
- OAuth 2.0 state argument with the H_NORMALIZED_PAYTO.
+ OAuth 2.0 state argument, as issued by the exchange in the
+ authorization request: the H_NORMALIZED_PAYTO, a ``-`` and a tag
+ binding the state to the KYC process. Requests whose state does
+ not match the currently running KYC process are refused without
+ changing the process, whether they carry a ``code`` or an ``error``.
.. note::
@@ -59,6 +63,11 @@
a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`401 Unauthorized`:
The provided authorization token is invalid.
+ :http:statuscode:`403 Forbidden`:
+ The KYC process failed, or, with the OAuth 2.0 logic, the
+ ``state`` was not issued for the running KYC process. In the
+ latter case the KYC process remains unchanged and the response
+ comes with a code of ``TALER_EC_GENERIC_FORBIDDEN``.
:http:statuscode:`404 Not found`:
The payment target is unknown.
This response comes with a standard `ErrorDetail` response with
diff --git a/taler-kyc-manual.rst b/taler-kyc-manual.rst
@@ -1255,6 +1255,24 @@ This template is instantiated using the following information:
* message: String; could be NULL; text elaborating on the details of the failure
+oauth2-state-invalid
+--------------------
+
+The ``state`` of the request to the ``/kyc-proof/`` endpoint was not the one
+the exchange issued for the KYC process currently running for the account,
+so the request was ignored (HTTP 403 Forbidden).
+
+This template is instantiated using the following information:
+
+ * ec: Integer; numeric Taler error code, should be shown to indicate the
+ error compactly for reporting to developers
+
+ * hint: String; human-readable Taler error code, should be shown for the
+ user to understand the error
+
+ * message: String; additional error message elaborating on what was wrong
+
+
persona-exchange-unauthorized
-----------------------------
