Merge remote-tracking branch 'refs/remotes/origin/master'

1 files changed, 168 insertions, 26 deletions

diff --git a/core/api-challenger.rst b/core/api-challenger.rst
index 914d8d01..f8631977 100644
--- a/core/api-challenger.rst
+++ b/core/api-challenger.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2023 Taler Systems SA
+  Copyright (C) 2023, 2024 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
@@ -29,19 +29,19 @@ The high-level flow is that an OAuth 2.0 client is first registered with the
 challenger service (via command-line). Using the command-line tool will print
 the resulting client ID to the console.
 
-  .. note::
+.. note::
 
-     The current service mandates that redirection URIs
-     start with "http://" or "https://". See issue #7838
-     for what should be done to lift this restriction.
+  The current service mandates that redirection URIs
+  start with "http://" or "https://". See issue #7838
+  for what should be done to lift this restriction.
 
-  .. note::
+.. note::
 
-     Right now, registration of a unique redirection URI is *mandatory* for
-     each client. If multiple redirection URIs are needed, it is suggested to
-     just register additional clients.  (While OAuth 2.0 would support not
-     registering fixed redirection URIs with a client, this is not recommended
-     as it would create an open redirector.)
+  Right now, registration of a unique redirection URI is *mandatory* for
+  each client. If multiple redirection URIs are needed, it is suggested to
+  just register additional clients.  (While OAuth 2.0 would support not
+  registering fixed redirection URIs with a client, this is not recommended
+  as it would create an open redirector.)
 
 Once a client is registered, that client can use the challenger service when
 it needs a user to prove that the user is able to receive messages at a
@@ -61,13 +61,13 @@ of the challenger service, adding its ``state``, ``client_id`` and
 redirect URI registered with the client. From this endpoint, the challenger
 service will return a Web page asking the user to provide its address.
 
-  .. note::
+.. note::
 
-    Challenger is a bit unusual in that the ``$NONCE`` in the endpoint URL
-    makes the authorization endpoint URL (deliberately) unpredictable, while
-    for many other OAuth 2.0 APIs this endpoint is static. However, this is
-    compliant with OAuth 2.0 as determining the authorization URL is left out
-    of the scope of the standard.
+  Challenger is a bit unusual in that the ``$NONCE`` in the endpoint URL
+  makes the authorization endpoint URL (deliberately) unpredictable, while
+  for many other OAuth 2.0 APIs this endpoint is static. However, this is
+  compliant with OAuth 2.0 as determining the authorization URL is left out
+  of the scope of the standard.
 
 When the user has filled in the form with their address, it will be submitted
 to the ``/challenge/$NONCE`` endpoint and the challenger service will send a
@@ -99,7 +99,7 @@ Receiving Configuration
 .. http:get:: /config
 
   Obtain the key configuration settings of the storage service.
-  This specification corresponds to ``current`` protocol being version **0**.
+  This specification corresponds to ``current`` protocol being version **1**.
 
   **Response:**
 
@@ -168,6 +168,16 @@ Login
   endpoint is used by the user-agent. It will return a form to enter the
   address.
 
+  The NONCE is a unique value identifying the challenge, should be shown to
+  the user so that they can recognize it when they receive the TAN code.
+
+  This endpoint typically also supports requests with the "Accept" header
+  requesting "text/html".  In this case, an HTML response using the template
+  :ref:`enter-$ADDRESS_TYPE-form <challenger_enter-address_type-form>` is
+  returned. If the backend installation does not include the required HTML
+  templates, a 406 status code is returned.
+
+
   **Request:**
 
   :query response_type: Must be ``code``
@@ -179,10 +189,55 @@ Login
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The body contains a form to be submitted by the user-agent.
+    If the request ask for application/json then the response is
+    a `ChallengeStatus`. Since protocol **v1**.
+    Otherwise, the body contains a form to be submitted by the user-agent
+    using the template :ref:`enter-$ADDRESS_TYPE-form <challenger_enter-address_type-form>`.
     The form will ask the user to specify their address.
+  :http:statuscode:`400 Bad Request`:
+    The request does not follow the spec.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`invalid-request <challenger_invalid-request>`.
   :http:statuscode:`404 Not found`:
-    The backup service is unaware of a matching $NONCE.
+    The service is unaware of a matching challenge.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`validation-unknown <challenger_validation-unknown>`.
+  :http:statuscode:`406 Not Acceptable`:
+    The client ask for "text/html" and the backend installation does
+    not include the required HTML templates.
+  :http:statuscode:`500 Internal Server Error`:
+    Server is not able to respond due to internal problems.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`internal-error <challenger_internal-error>`.
+
+  .. ts:def:: ChallengeStatus
+
+    interface ChallengeStatus {
+      // Object; map of keys (names of the fields of the address
+      // to be entered by the user) to objects with a "regex" (string)
+      // containing an extended Posix regular expression for allowed
+      // address field values, and a "hint"/"hint_i18n" giving a
+      // human-readable explanation to display if the value entered
+      // by the user does not match the regex. Keys that are not mapped
+      // to such an object have no restriction on the value provided by
+      // the user.  See "ADDRESS_RESTRICTIONS" in the challenger configuration.
+      restrictions: Object;
+
+      // indicates if the given address cannot be changed anymore, the
+      // form should be read-only if set to true.
+      fix_address: boolean;
+
+      // form values from the previous submission if available, details depend
+      // on the ``ADDRESS_TYPE``, should be used to pre-populate the form
+      last_address: Object;
+
+      // number of times the address can still be changed, may or may not be
+      // shown to the user
+      changes_left: Integer;
+    }
 
 
 .. _challenger-challenge:
@@ -204,15 +259,57 @@ Challenge
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The body contains a form asking for the answer to
-    the challenge to be entered by the user.
-  :http:statuscode:`404 Not found`:
-    The challenger service is unaware of a matching nonce.
+    If the request ask for application/json the response is `ChallengeCreateResponse`. Since protocol **v1**.
+    Otherwise, the body contains a form asking for the answer to
+    the challenge to be entered by the user using the
+    template :ref:`enter-tan-form <challenger_enter-tan-form>`.
+  :http:statuscode:`400 Bad Request`:
+    The request does not follow the spec.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`invalid-request <challenger_invalid-request>`.
+  :http:statuscode:`404 Not Found`:
+    The service is unaware of a matching challenge.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`validation-unknown <challenger_validation-unknown>`.
+  :http:statuscode:`406 Not Acceptable`:
+    The client ask for "text/html" and the backend installation does
+    not include the required HTML templates.
   :http:statuscode:`429 Too Many Requests`:
     There have been too many attempts to request challenge
     transmissions for this $NONCE. The user-agent should
     wait and (eventually) request a fresh nonce to be set
     up by the client.
+  :http:statuscode:`500 Internal Server Error`:
+    Server is not able to respond due to internal problems.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`internal-error <challenger_internal-error>`.
+
+  .. ts:def:: ChallengeCreateResponse
+
+    interface ChallengeCreateResponse {
+
+      // how many more attempts are allowed, might be shown to the user,
+      // highlighting might be appropriate for low values such as 1 or 2 (the
+      // form will never be used if the value is zero)
+      attempts_left: Integer;
+
+      // the address that is being validated, might be shown or not
+      address: Object;
+
+      // true if we just retransmitted the challenge, false if we sent a
+      // challenge recently and thus refused to transmit it again this time;
+      // might make a useful hint to the user
+      transmitted: boolean;
+
+      // timestamp explaining when we would re-transmit the challenge the next
+      // time (at the earliest) if requested by the user
+      next_tx_time: String;
+
+    }
+
 
 
 .. _challenger-solve:
@@ -239,16 +336,61 @@ Solve
     by the client (during registration and again upon ``/authorize``),
     plus a ``code`` argument with the authorization code, and the
     ``state`` argument from the ``/authorize`` endpoint.
+  :http:statuscode:`400 Bad Request`:
+    The request does not follow the spec.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`invalid-request <challenger_invalid-request>`.
   :http:statuscode:`403 Forbidden`:
-    The solution of the user to the challenge is invalid.
+    If the request ask for application/json the response is `InvalidPinResponse`. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`invalid-pin <challenger_invalid-pin>`.
   :http:statuscode:`404 Not found`:
     The service is unaware of a matching challenge.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`validation-unknown <challenger_validation-unknown>`.
   :http:statuscode:`429 Too Many Requests`:
     There have been too many attempts to solve the challenge
     for this address (and $NONCE). The user-agent should
     either try a different address (or wait and (eventually)
     request a fresh nonce to be set up by the client).
-
+  :http:statuscode:`500 Internal Server Error`:
+    Server is not able to respond due to internal problems.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **v1**.
+    Otherwise, the body contains information using the template :ref:`internal-error <challenger_internal-error>`.
+
+  .. ts:def:: InvalidPinResponse
+
+    interface InvalidPinResponse {
+      // numeric Taler error code, should be shown to indicate the error
+      // compactly for reporting to developers
+      ec: Integer;
+
+      // human-readable Taler error code, should be shown for the user to
+      // understand the error
+      hint: String;
+
+      // how many times is the user still allowed to change the address;
+      // if 0, the user should not be shown a link to jump to the
+      // address entry form
+      addresses_left: Integer;
+
+      // how many times might the PIN still be retransmitted
+      pin_transmissions_left: Integer;
+
+      // how many times might the user still try entering the PIN code
+      auth_attempts_left: Integer;
+
+      // if true, the PIN was not even evaluated as the user previously
+      // exhausted the number of attempts
+      exhausted: boolean;
+
+      // if true, the PIN was not even evaluated as no challenge was ever
+      // issued (the user must have skipped the step of providing their
+      // address first!)
+      no_challenge: boolean;
+    }
 
 .. _challenger-auth: