aboutsummaryrefslogtreecommitdiff
path: root/doc/sphinx/reducer.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/sphinx/reducer.rst')
-rw-r--r--doc/sphinx/reducer.rst228
1 files changed, 129 insertions, 99 deletions
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:
1459 } 1459 }
1460 } 1460 }
1461 1461
1462 - **body**: Here, the server provided an HTTP reply for 1462 - **body**: Here, the server provided an HTTP reply for
1463 how to solve the challenge, but the reducer could not parse 1463 how to solve the challenge, but the reducer could not parse
1464 them into a known format. A mime-type may be provided and may 1464 them into a known format. A mime-type may be provided and may
1465 help parse the details. 1465 help parse the details.
1466 1466
1467 .. code-block:: json 1467 .. code-block:: json
1468 1468
1469 { 1469 {
1470 "recovery_state": "CHALLENGE_SOLVING", 1470 "recovery_state": "CHALLENGE_SOLVING",
1471 "recovery_information": { 1471 "recovery_information": {
1472 "...": "..." 1472 "...": "..."
1473 } 1473 }
1474 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", 1474 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
1475 "challenge_feedback": { 1475 "challenge_feedback": {
1476 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { 1476 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
1477 "state": "body", 1477 "state": "body",
1478 "body": "CROCKFORDBASE32ENCODEDBODY", 1478 "body": "CROCKFORDBASE32ENCODEDBODY",
1479 "http_status": 403, 1479 "http_status": 403,
1480 "mime_type" : "anything/possible" 1480 "mime_type" : "anything/possible"
1481 } 1481 }
1482 } 1482 }
1483 } 1483 }
1484 1484
1485 - **hint**: Here, the server provided human-readable hint for 1485 - **hint**: Here, the server provided human-readable hint for
1486 how to solve the challenge. Note that the ``hint`` provided this 1486 how to solve the challenge. Note that the ``hint`` provided this
1487 time is from the Anastasis provider and may differ from the ``instructions`` 1487 time is from the Anastasis provider and may differ from the ``instructions``
1488 for the challenge under ``recovery_information``: 1488 for the challenge under ``recovery_information``:
1489 1489
1490 .. code-block:: json 1490 .. code-block:: json
1491 1491
1492 { 1492 {
1493 "recovery_state": "CHALLENGE_SOLVING", 1493 "recovery_state": "CHALLENGE_SOLVING",
1494 "recovery_information": { 1494 "recovery_information": {
1495 "...": "..." 1495 "...": "..."
1496 } 1496 }
1497 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", 1497 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
1498 "challenge_feedback": { 1498 "challenge_feedback": {
1499 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { 1499 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
1500 "state": "hint", 1500 "state": "hint",
1501 "hint": "Recovery TAN send to email mail@DOMAIN", 1501 "hint": "Recovery TAN send to email mail@DOMAIN",
1502 "http_status": 403 1502 "http_status": 403
1503 } 1503 }
1504 }
1505 }
1506
1507 - **details**: Here, the server provided a detailed JSON status response
1508 related to solving the challenge:
1509
1510 .. code-block:: json
1511
1512 {
1513 "recovery_state": "CHALLENGE_SOLVING",
1514 "recovery_information": {
1515 "...": "..."
1516 }
1517 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
1518 "challenge_feedback": {
1519 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
1520 "state": "details",
1521 "details": {
1522 "code": 8111,
1523 "hint": "The client's response to the challenge was invalid.",
1524 "detail" : null
1525 },
1526 "http_status": 403
1504 } 1527 }
1505 } 1528 }
1529 }
1506 1530
1507 - **details**: Here, the server provided a detailed JSON status response 1531 - **redirect**: To solve the challenge, the user must visit the indicated
1508 related to solving the challenge: 1532 Web site at ``redirect_url``, for example to perform video authentication:
1509 1533
1510 .. code-block:: json 1534 .. code-block:: json
1511 1535
1512 { 1536 {
1513 "recovery_state": "CHALLENGE_SOLVING", 1537 "recovery_state": "CHALLENGE_SOLVING",
1514 "recovery_information": { 1538 "recovery_information": {
1515 "...": "..." 1539 "...": "..."
1516 } 1540 }
1517 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", 1541 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
1518 "challenge_feedback": { 1542 "challenge_feedback": {
1519 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { 1543 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
1520 "state": "details", 1544 "state": "redirect",
1521 "details": { 1545 "redirect_url": "https://videoconf.example.com/",
1522 "code": 8111, 1546 "http_status": 303
1523 "hint": "The client's response to the challenge was invalid.",
1524 "detail" : null
1525 },
1526 "http_status": 403
1527 }
1528 } 1547 }
1529 } 1548 }
1549 }
1530 1550
1531 - **redirect**: To solve the challenge, the user must visit the indicated 1551 - **server-failure**: This indicates that the Anastasis provider encountered
1532 Web site at ``redirect_url``, for example to perform video authentication: 1552 a failure and recovery using this challenge cannot proceed at this time.
1553 Examples for failures might be that the provider is unable to send SMS
1554 messages at this time due to an outage. The body includes details about
1555 the failure. The user may try again later or continue with other challenges.
1533 1556
1534 .. code-block:: json 1557 .. code-block:: json
1535 1558
1536 { 1559 {
1537 "recovery_state": "CHALLENGE_SOLVING", 1560 "recovery_state": "CHALLENGE_SELECTING",
1538 "recovery_information": { 1561 "recovery_information": {
1539 "...": "..." 1562 "...": "..."
1540 }
1541 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
1542 "challenge_feedback": {
1543 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
1544 "state": "redirect",
1545 "redirect_url": "https://videoconf.example.com/",
1546 "http_status": 303
1547 }
1548 }
1549 } 1563 }
1564 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
1565 "challenge_feedback": {
1566 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
1567 "state": "server-failure",
1568 "http_status": "500",
1569 "error_code": 52
1570 }
1571 }
1572 }
1550 1573
1551 - **server-failure**: This indicates that the Anastasis provider encountered 1574 - **truth-unknown**: This indicates that the Anastasis provider is unaware of
1552 a failure and recovery using this challenge cannot proceed at this time. 1575 the specified challenge. This is typically a permanent failure, and user
1553 Examples for failures might be that the provider is unable to send SMS 1576 interfaces should not allow users to re-try this challenge.
1554 messages at this time due to an outage. The body includes details about
1555 the failure. The user may try again later or continue with other challenges.
1556 1577
1557 .. code-block:: json 1578 .. code-block:: json
1558 1579
1559 { 1580 {
1560 "recovery_state": "CHALLENGE_SELECTING", 1581 "recovery_state": "CHALLENGE_SELECTING",
1561 "recovery_information": { 1582 "recovery_information": {
1562 "...": "..." 1583 "...": "..."
1563 } 1584 }
1564 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", 1585 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
1565 "challenge_feedback": { 1586 "challenge_feedback": {
1566 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { 1587 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
1567 "state": "server-failure", 1588 "state": "truth-unknown",
1568 "http_status": "500", 1589 "error_code": 8108
1569 "error_code": 52 1590 }
1570 } 1591 }
1571 } 1592 }
1572 }
1573 1593
1574 - **truth-unknown**: This indicates that the Anastasis provider is unaware of 1594 - **rate-limit-exceeded**:
1575 the specified challenge. This is typically a permanent failure, and user
1576 interfaces should not allow users to re-try this challenge.
1577 1595
1578 .. code-block:: json 1596 .. code-block:: json
1579 1597
@@ -1585,13 +1603,13 @@ that applications must all handle. States other than ``solved`` are:
1585 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", 1603 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
1586 "challenge_feedback": { 1604 "challenge_feedback": {
1587 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { 1605 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
1588 "state": "truth-unknown", 1606 "state": "rate-limit-exceeded",
1589 "error_code": 8108 1607 "error_code": 8121
1590 } 1608 }
1591 } 1609 }
1592 } 1610 }
1593 1611
1594 - **rate-limit-exceeded**: 1612 - **authentication-timeout**:
1595 1613
1596 .. code-block:: json 1614 .. code-block:: json
1597 1615
@@ -1603,12 +1621,24 @@ that applications must all handle. States other than ``solved`` are:
1603 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", 1621 "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
1604 "challenge_feedback": { 1622 "challenge_feedback": {
1605 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { 1623 "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
1606 "state": "rate-limit-exceeded", 1624 "state": "authentication-timeout",
1607 "error_code": 8121 1625 "error_code": 8122
1608 } 1626 }
1609 } 1627 }
1610 } 1628 }
1611 1629
1630
1631**poll:**
1632
1633With 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:
1634
1635.. code-block:: json
1636
1637 {
1638 "timeout" : { "d_ms" : 5000 },
1639 }
1640
1641
1612**pay:** 1642**pay:**
1613 1643
1614With a ``pay`` transition, the application indicates to the reducer that 1644With a ``pay`` transition, the application indicates to the reducer that