post-solve-NONCE.rst (3320B)
1 .. http:post:: /solve/$NONCE 2 3 Used by the user-agent to submit an answer to the challenge. If the answer 4 is correct, the user will be redirected to the client's redirect URI, 5 otherwise the user may be given another chance to complete the process. 6 7 **Request:** 8 9 Body should use the mime-type "application/x-www-form-urlencoded". 10 The posted form data must contain a "pin" field. 11 12 **Response:** 13 14 :http:statuscode:`200 OK`: 15 If the request ask for application/json the response is 16 a `ChallengeSolveResponse`. Since protocol **v2**. 17 :http:statuscode:`302 Found`: 18 Only possible if request didn't ask for application/json. Since protocol **v2**. 19 The user is redirected to the redirect URI of the client to pass the 20 grant to the client. The target will be the redirect URI specified 21 by the client (during registration and again upon ``/authorize``), 22 plus a ``code`` argument with the authorization code, and the 23 ``state`` argument from the ``/authorize`` endpoint. 24 :http:statuscode:`400 Bad Request`: 25 The request does not follow the spec. 26 The response will include error 27 code, hint and detail. Since protocol **v1**. 28 :http:statuscode:`403 Forbidden`: 29 The response is `InvalidPinResponse`. Since protocol **v1**. 30 :http:statuscode:`404 Not found`: 31 The service is unaware of a matching challenge. 32 The response will include error 33 code, hint and detail. Since protocol **v1**. 34 :http:statuscode:`429 Too Many Requests`: 35 There have been too many attempts to solve the challenge 36 for this address (and $NONCE). The user-agent should 37 either try a different address (or wait and (eventually) 38 request a fresh nonce to be set up by the client). 39 The response will include error 40 code, hint and detail. Since protocol **v2**. 41 :http:statuscode:`500 Internal Server Error`: 42 Server is not able to respond due to internal problems. 43 The response will include error 44 code, hint and detail. Since protocol **v1**. 45 46 .. ts:def:: ChallengeSolveResponse 47 48 // Union discriminated by the "type" field. 49 type ChallengeSolveResponse = ChallengeRedirect | InvalidPinResponse; 50 51 .. ts:def:: InvalidPinResponse 52 53 interface InvalidPinResponse { 54 // Union discriminator field. 55 type: "pending"; 56 57 // numeric Taler error code, should be shown to indicate the error 58 // compactly for reporting to developers 59 code: Integer; 60 61 // human-readable Taler error code, should be shown for the user to 62 // understand the error 63 hint: string; 64 65 // how many times is the user still allowed to change the address; 66 // if 0, the user should not be shown a link to jump to the 67 // address entry form 68 addresses_left: Integer; 69 70 // how many times might the PIN still be retransmitted 71 pin_transmissions_left: Integer; 72 73 // how many times might the user still try entering the PIN code 74 auth_attempts_left: Integer; 75 76 // if true, the PIN was not even evaluated as the user previously 77 // exhausted the number of attempts 78 exhausted: boolean; 79 80 // if true, the PIN was not even evaluated as no challenge was ever 81 // issued (the user must have skipped the step of providing their 82 // address first!) 83 no_challenge: boolean; 84 }