taler-docs

commit a582ba3d0c77a53dbeb5af00eec28930a071e5c0
parent c3c23c70d6622181fec568d9a0aef88db6d74845
Author: Christian Grothoff <christian@grothoff.org>
Date:   Sun, 26 Apr 2026 09:05:29 +0200

improve spec accuracy

Diffstat:
M
core/api-challenger.rst
 | 
69
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----------

1 file changed, 58 insertions(+), 11 deletions(-)
diff --git a/core/api-challenger.rst b/core/api-challenger.rst
@@ -120,11 +120,12 @@ Receiving Configuration
 
   **Response:**
 
-  Returns a `ChallengerTermsOfServiceResponse`.
+  :http:statuscode:`200 OK`:
+    Response is a `ChallengerConfigurationResponse`.
 
-  .. ts:def:: ChallengerTermsOfServiceResponse
+  .. ts:def:: ChallengerConfigurationResponse
 
-    interface ChallengerTermsOfServiceResponse {
+    interface ChallengerConfigurationResponse {
       // Name of the service
       name: "challenger";
 
@@ -135,7 +136,7 @@ Receiving Configuration
 
       // URN of the implementation (needed to interpret 'revision' in version).
       // @since v0, may become mandatory in the future.
-      implementation?: string;
+     implementation?: string;
 
       // @since **v2**.
       // Object; map of keys (names of the fields of the address
@@ -351,6 +352,13 @@ Challenge
     The request does not follow the spec.
     The response will include error
     code, hint and detail. Since protocol **v1**.
+  :http:statuscode:`403 Forbidden`:
+    The address being submitted differs from the previously
+    submitted address but the validation process was set up
+    as ``read_only`` and thus the address cannot be changed.
+    Returned with
+    ``TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_READ_ONLY``.
+    Since protocol **v4**.
   :http:statuscode:`404 Not Found`:
     The service is unaware of a matching challenge.
     The response will include error
@@ -363,12 +371,17 @@ Challenge
     transmissions for this $NONCE. The user-agent should
     wait and (eventually) request a fresh nonce to be set
     up by the client.
-    The response will include error
-    code, hint and detail. Since protocol **v2**.
+    Returned with ``TALER_EC_CHALLENGER_TOO_MANY_ATTEMPTS``.
+    Since protocol **v2**.
   :http:statuscode:`500 Internal Server Error`:
     Server is not able to respond due to internal problems.
     The response will include error
     code, hint and detail. Since protocol **v1**.
+  :http:statuscode:`502 Bad Gateway`:
+    The challenger service failed to launch or communicate with
+    its helper process for delivering the challenge (SMS, e-mail,
+    postal mail).  Returned with
+    ``TALER_EC_CHALLENGER_HELPER_EXEC_FAILED``.
 
   .. ts:def:: ChallengeResponse
 
@@ -536,13 +549,42 @@ Auth
   as well as also returning GNU Taler style error messages.
 
   :http:statuscode:`200 OK`:
-    The body will be a `ChallengerAuthResponse`
+    The body will be a `ChallengerAuthResponse`.
+  :http:statuscode:`400 Bad Request`:
+    A required POST field (``grant_type``, ``client_id``,
+    ``client_secret``, ``code`` or ``redirect_uri``) is missing
+    or malformed, or ``grant_type`` is not ``authorization_code``.
+    Usually returned with ``TALER_EC_GENERIC_PARAMETER_MISSING``
+    or ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
   :http:statuscode:`401 Unauthorized`:
-    The ``code_verifier`` is not matching the saved ones. (Since **v3**)
-  :http:statuscode:`403 Forbidden`:
-    The credentials of the client are invalid.
+    Authentication of the client failed.  Returned (per
+    RFC 6749, section 5.2) when the client credentials are
+    invalid, when the supplied ``code`` is malformed or does
+    not match the validation, when the ``redirect_uri`` does
+    not match the one registered with the client, or when the
+    ``code_verifier`` does not match the saved
+    ``code_challenge``.  Returned with
+    ``TALER_EC_CHALLENGER_GENERIC_CLIENT_FORBIDDEN_BAD_REDIRECT_URI``,
+    ``TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_BAD_CODE``,
+    ``TALER_EC_CHALLENGER_GENERIC_VALIDATION_UNKNOWN`` or
+    ``TALER_EC_CHALLENGER_GRANT_UNKNOWN``.
+    PKCE-related rejections are since protocol **v3**.
   :http:statuscode:`404 Not found`:
-    The service is unaware of a matching login process.
+    The service is unaware of a matching login process or client.
+    Returned with error codes of
+    ``TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKOWN``
+  :http:statuscode:`409 Conflict`:
+    A ``code`` was presented for a validation process for which
+    the user has not (yet) submitted any address, so the token
+    cannot be issued.  Returned with
+    ``TALER_EC_CHALLENGER_MISSING_ADDRESS``.
+  :http:statuscode:`500 Internal Server Error`:
+    The challenger service encountered an internal error,
+    for example a database failure or a failure of the SHA-256
+    or Base64 helpers used for PKCE verification.
+    Error codes used are:
+    * ``TALER_EC_CHALLENGER_GENERIC_DB_FETCH_FAILED``
+    * ``TALER_EC_CHALLENGER_GENERIC_DB_STORE_FAILED``
 
   **Details::**
 
@@ -585,6 +627,11 @@ Info
     The bearer token is missing or invalid (malformed).
   :http:statuscode:`404 Not found`:
     The bearer token is invalid (includes unknown or expired).
+    Returned with ``TALER_EC_CHALLENGER_GRANT_UNKNOWN``.
+  :http:statuscode:`500 Internal Server Error`:
+    The challenger service encountered an internal error,
+    typically a database failure.  Usually returned with
+    ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
 
   **Details::**