change in challenger spec

1 files changed, 61 insertions, 14 deletions

diff --git a/core/api-challenger.rst b/core/api-challenger.rst
index 759d4e70..e95434ef 100644
--- a/core/api-challenger.rst
+++ b/core/api-challenger.rst
@@ -120,6 +120,19 @@ Receiving Configuration
       // @since v0, may become mandatory in the future.
       implementation?: string;
 
+      // @since v2.
+      // 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;
+
+      // @since v2.
+      address_type: "email" | "phone";
     }
 
 .. _challenger-setup:
@@ -216,15 +229,8 @@ Login
   .. 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;
+      // @deprecated since v2, use /config
+      restrictions?: Object;
 
       // indicates if the given address cannot be changed anymore, the
       // form should be read-only if set to true.
@@ -232,11 +238,29 @@ Login
 
       // 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;
+      last_address?: Object;
 
       // number of times the address can still be changed, may or may not be
       // shown to the user
       changes_left: Integer;
+
+      // when we would re-transmit the challenge the next
+      // time (at the earliest) if requested by the user
+      // only present if challenge already created
+      // @since v2
+      retransmission_time: Timestamp;
+
+      // how many times might the PIN still be retransmitted
+
+      // how many times might the PIN still be retransmitted
+      // only present if challenge already created
+      // @since v2
+      pin_transmissions_left?: Integer;
+
+      // how many times might the user still try entering the PIN code
+      // only present if challenge already created
+      // @since v2
+      auth_attempts_left?: Integer;
     }
 
 
@@ -259,10 +283,17 @@ Challenge
   **Response:**
 
   :http:statuscode:`200 OK`:
-    If the request ask for application/json the response is `ChallengeCreateResponse`. Since protocol **v1**.
+    If the request ask for application/json the response is `ChallengeResponse`. Since protocol **v2**.
     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:`302 Found`:
+    Only possible if request didn't ask for application/json. Since protocol **v2**.
+    The user is redirected to the redirect URI of the client to pass the
+    grant to the client.  The target will be the redirect URI specified
+    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
@@ -289,6 +320,14 @@ Challenge
 
   .. ts:def:: ChallengeCreateResponse
 
+    interface ChallengeResponse = ChallengeRedirect | ChallengeCreateResponse
+
+    // @since v2
+    interface ChallengeRedirect {
+      // challenge is completed, use should redirect here
+      redirect_url: string;
+    }
+
     interface ChallengeCreateResponse {
 
       // how many more attempts are allowed, might be shown to the user,
@@ -304,10 +343,13 @@ Challenge
       // 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;
+      // @deprecated in v2, use retransmission_time
+      next_tx_time?: string;
 
+      // when we would re-transmit the challenge the next
+      // time (at the earliest) if requested by the user
+      // @since v2
+      retransmission_time: Timestamp;
     }
 
 
@@ -330,7 +372,10 @@ Solve
 
   **Response:**
 
+  :http:statuscode:`200 OK`:
+    If the request ask for application/json the response is `ChallengeSolveResponse`. Since protocol **v2**.
   :http:statuscode:`302 Found`:
+    Only possible if request didn't ask for application/json. Since protocol **v2**.
     The user is redirected to the redirect URI of the client to pass the
     grant to the client.  The target will be the redirect URI specified
     by the client (during registration and again upon ``/authorize``),
@@ -362,6 +407,8 @@ Solve
 
   .. ts:def:: InvalidPinResponse
 
+    type ChallengeSolveResponse = ChallengerRedirect | InvalidPinResponse;
+
     interface InvalidPinResponse {
       // numeric Taler error code, should be shown to indicate the error
       // compactly for reporting to developers