From 677c7e87a5da584e68194c9cca19a91191c3140c Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 19 Aug 2021 14:43:39 +0200 Subject: -implement 'poll' transition in state machine --- doc/sphinx/reducer.rst | 228 ++++++++++++++++++++++++++++--------------------- 1 file changed, 129 insertions(+), 99 deletions(-) (limited to 'doc') diff --git a/doc/sphinx/reducer.rst b/doc/sphinx/reducer.rst index e5f1699..68df5b1 100644 --- a/doc/sphinx/reducer.rst +++ b/doc/sphinx/reducer.rst @@ -1459,121 +1459,139 @@ that applications must all handle. States other than ``solved`` are: } } - - **body**: Here, the server provided an HTTP reply for - how to solve the challenge, but the reducer could not parse - them into a known format. A mime-type may be provided and may - help parse the details. + - **body**: Here, the server provided an HTTP reply for + how to solve the challenge, but the reducer could not parse + them into a known format. A mime-type may be provided and may + help parse the details. - .. code-block:: json + .. code-block:: json - { - "recovery_state": "CHALLENGE_SOLVING", - "recovery_information": { - "...": "..." - } - "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", - "challenge_feedback": { - "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { - "state": "body", - "body": "CROCKFORDBASE32ENCODEDBODY", - "http_status": 403, - "mime_type" : "anything/possible" - } - } - } + { + "recovery_state": "CHALLENGE_SOLVING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "body", + "body": "CROCKFORDBASE32ENCODEDBODY", + "http_status": 403, + "mime_type" : "anything/possible" + } + } + } - - **hint**: Here, the server provided human-readable hint for - how to solve the challenge. Note that the ``hint`` provided this - time is from the Anastasis provider and may differ from the ``instructions`` - for the challenge under ``recovery_information``: + - **hint**: Here, the server provided human-readable hint for + how to solve the challenge. Note that the ``hint`` provided this + time is from the Anastasis provider and may differ from the ``instructions`` + for the challenge under ``recovery_information``: - .. code-block:: json + .. code-block:: json - { - "recovery_state": "CHALLENGE_SOLVING", - "recovery_information": { - "...": "..." - } - "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", - "challenge_feedback": { - "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { - "state": "hint", - "hint": "Recovery TAN send to email mail@DOMAIN", - "http_status": 403 - } + { + "recovery_state": "CHALLENGE_SOLVING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "hint", + "hint": "Recovery TAN send to email mail@DOMAIN", + "http_status": 403 + } + } + } + + - **details**: Here, the server provided a detailed JSON status response + related to solving the challenge: + + .. code-block:: json + + { + "recovery_state": "CHALLENGE_SOLVING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "details", + "details": { + "code": 8111, + "hint": "The client's response to the challenge was invalid.", + "detail" : null + }, + "http_status": 403 } } + } - - **details**: Here, the server provided a detailed JSON status response - related to solving the challenge: + - **redirect**: To solve the challenge, the user must visit the indicated + Web site at ``redirect_url``, for example to perform video authentication: - .. code-block:: json + .. code-block:: json - { - "recovery_state": "CHALLENGE_SOLVING", - "recovery_information": { - "...": "..." - } - "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", - "challenge_feedback": { - "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { - "state": "details", - "details": { - "code": 8111, - "hint": "The client's response to the challenge was invalid.", - "detail" : null - }, - "http_status": 403 - } + { + "recovery_state": "CHALLENGE_SOLVING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "redirect", + "redirect_url": "https://videoconf.example.com/", + "http_status": 303 } } + } - - **redirect**: To solve the challenge, the user must visit the indicated - Web site at ``redirect_url``, for example to perform video authentication: + - **server-failure**: This indicates that the Anastasis provider encountered + a failure and recovery using this challenge cannot proceed at this time. + Examples for failures might be that the provider is unable to send SMS + messages at this time due to an outage. The body includes details about + the failure. The user may try again later or continue with other challenges. - .. code-block:: json + .. code-block:: json - { - "recovery_state": "CHALLENGE_SOLVING", - "recovery_information": { - "...": "..." - } - "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", - "challenge_feedback": { - "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { - "state": "redirect", - "redirect_url": "https://videoconf.example.com/", - "http_status": 303 - } - } + { + "recovery_state": "CHALLENGE_SELECTING", + "recovery_information": { + "...": "..." } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "server-failure", + "http_status": "500", + "error_code": 52 + } + } + } - - **server-failure**: This indicates that the Anastasis provider encountered - a failure and recovery using this challenge cannot proceed at this time. - Examples for failures might be that the provider is unable to send SMS - messages at this time due to an outage. The body includes details about - the failure. The user may try again later or continue with other challenges. + - **truth-unknown**: This indicates that the Anastasis provider is unaware of + the specified challenge. This is typically a permanent failure, and user + interfaces should not allow users to re-try this challenge. .. code-block:: json - { - "recovery_state": "CHALLENGE_SELECTING", - "recovery_information": { - "...": "..." - } - "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", - "challenge_feedback": { - "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { - "state": "server-failure", - "http_status": "500", - "error_code": 52 - } - } - } + { + "recovery_state": "CHALLENGE_SELECTING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "truth-unknown", + "error_code": 8108 + } + } + } - - **truth-unknown**: This indicates that the Anastasis provider is unaware of - the specified challenge. This is typically a permanent failure, and user - interfaces should not allow users to re-try this challenge. + - **rate-limit-exceeded**: .. code-block:: json @@ -1585,13 +1603,13 @@ that applications must all handle. States other than ``solved`` are: "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", "challenge_feedback": { "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { - "state": "truth-unknown", - "error_code": 8108 + "state": "rate-limit-exceeded", + "error_code": 8121 } } } - - **rate-limit-exceeded**: + - **authentication-timeout**: .. code-block:: json @@ -1603,12 +1621,24 @@ that applications must all handle. States other than ``solved`` are: "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", "challenge_feedback": { "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { - "state": "rate-limit-exceeded", - "error_code": 8121 + "state": "authentication-timeout", + "error_code": 8122 } } } + +**poll:** + +With a ``poll`` transition, the application indicates that it wants to wait longer for one or more of the challenges that are in state ``authentication-timeout`` to possibly complete. While technically optional, the ``timeout`` argument should really be provided to enable long-polling, for example: + +.. code-block:: json + + { + "timeout" : { "d_ms" : 5000 }, + } + + **pay:** With a ``pay`` transition, the application indicates to the reducer that -- cgit v1.2.3