Add documentation

wultra · Nov 10, 2023 · 067c201 · 067c201
1 parent 0401050
commit 067c201
Show file tree

Hide file tree

Showing 2 changed files with 100 additions and 14 deletions.
diff --git a/docs/Error-Handling.md b/docs/Error-Handling.md
@@ -7,17 +7,18 @@ Every `ApiError` consist of:
 
 ## Known API Error codes
 
-| Error Code | Description |
-|---|---|
-|`ERROR_GENERIC`|When unexpected error happened|
-|`POWERAUTH_AUTH_FAIL`|General authentication failure (wrong password, wrong activation state, etc...)|
-|`INVALID_REQUEST`|Invalid request sent - missing request object in the request|
-|`INVALID_ACTIVATION`|Activation is not valid (it is different from configured activation)|
-|`PUSH_REGISTRATION_FAILED`|Error code for a situation when registration to push notification fails|
-|`OPERATION_ALREADY_FINISHED`|Operation is already finished|
-|`OPERATION_ALREADY_FAILED`|Operation is already failed|
-|`OPERATION_ALREADY_CANCELED`|Operation is canceled|
-|`OPERATION_EXPIRED`|Operation is expired|
-|`ERR_AUTHENTICATION`|Error in case that PowerAuth authentication fails|
-|`ERR_SECURE_VAULT`|Error during secure vault unlocking|
-|`ERR_ENCRYPTION`|Returned in case encryption or decryption fails|
+| Error Code                   | Description |
+|------------------------------|---|
+| `ERROR_GENERIC`              |When unexpected error happened|
+| `POWERAUTH_AUTH_FAIL`        |General authentication failure (wrong password, wrong activation state, etc...)|
+| `INVALID_REQUEST`            |Invalid request sent - missing request object in the request|
+| `INVALID_ACTIVATION`         |Activation is not valid (it is different from configured activation)|
+| `PUSH_REGISTRATION_FAILED`   |Error code for a situation when registration to push notification fails|
+| `OPERATION_ALREADY_FINISHED` |Operation is already finished|
+| `OPERATION_ALREADY_FAILED`   |Operation is already failed|
+| `OPERATION_ALREADY_CANCELED` |Operation is canceled|
+| `OPERATION_EXPIRED`          |Operation is expired|
+| `OPERATION_FAILED`           |Default operation action failure|
+| `ERR_AUTHENTICATION`         |Error in case that PowerAuth authentication fails|
+| `ERR_SECURE_VAULT`           |Error during secure vault unlocking|
+| `ERR_ENCRYPTION`             |Returned in case encryption or decryption fails|
diff --git a/docs/Using-Operations-Service.md b/docs/Using-Operations-Service.md
@@ -11,6 +11,7 @@
 - [Operations API Reference](#operations-api-reference)
 - [UserOperation](#useroperation)
 - [Creating a Custom Operation](#creating-a-custom-operation)
+- [TOTP ProximityCheck](#totp-proximitycheck)
 ## Introduction
 <!-- end -->
 
@@ -407,6 +408,9 @@ class UserOperation: IOperation {
     // Accompanying information about the operation additional UI which should be presented such as
     // Pre-Approval Screen or Post-Approval Screen
     val ui: OperationUIData?
+
+    // Proximity Check Data to be passed when OTP is handed to the app
+    var proximityCheck: ProximityCheck? = null
 }
 ```
 
@@ -439,6 +443,61 @@ Attributes types:
 - `IMAGE` image row  
 - `UNKNOWN` fallback option when unknown attribute type is passed. Such attribute only contains the label.  
 
+Definition of `OperationUIData`:
+
+```kotlin
+class OperationUIData: Codable {
+    /// Confirm and Reject buttons should be flipped both in position and style
+    val flipButtons: Boolean?
+
+    /// Block approval when on call (for example when on a phone or Skype call)
+    val blockApprovalOnCall: Boolean?
+
+    /// UI for pre-approval operation screen
+    val preApprovalScreen: PreApprovalScreen?
+
+    /// UI for post-approval operation screen
+    ///
+    /// Type of PostApprovalScreen is presented with different classes (Starting with `PostApprovalScreen*`)
+    val postApprovalScreen: PostApprovalScreen?
+}
+```
+
+PreApprovalScreen types:
+
+- `WARNING`
+- `INFO`
+- `QR_SCAN` this type indicates that the `ProximityCheck` must be used for authorization
+- `UNKNOWN`
+
+PostApprovalScreen types:
+`PostApprovalScreen*` classes commonly contain `heading` and `message` and different payload data
+
+- `REVIEW` provides an array of operations attributes with data: type, id, label, and note
+- `REDIRECT` providing text for button, countdown, and redirection URL
+- `GENERIC` may contain any object
+
+Definition of `ProximityCheckData`:
+
+```kotlin
+class ProximityCheck: Codable {
+
+    /// Tha actual Time-based one time password
+    val totp: String
+
+    /// Type of the Proximity check
+    val type: ProximityCheckType
+
+    /// Timestamp when the operation was scanned (QR Code) or delivered to the device (Deeplink)
+    val timestampRequested: ZonedDateTime = ZonedDateTime.now()
+}
+```
+
+ProximityCheckType types:
+
+- `QR_CODE` TOTP was scanned from QR code
+- `DEEPLINK` TOTP was delivered to the app via Deeplink
+
 ## Creating a Custom Operation
 
 In some specific scenarios, you might need to approve or reject an operation that you received through a different channel than `getOperations`. In such cases, you can implement the `IOperation` interface in your custom class and then feed created objects to both `authorizeOperation` and `rejectOperation` methods.
@@ -461,5 +520,31 @@ interface IOperation {
      * Data for signing
      */
     val data: String
+
+    /** 
+     * Additional information with proximity check data 
+     */ 
+    var proximityCheck: ProximityCheck?
 }
 ```
+
+## TOTP ProximityCheck
+
+Two-Factor Authentication (2FA) using Time-Based One-Time Passwords (TOTP) in the Operations Service is facilitated through the use of ProximityCheck. This allows secure approval of operations through QR code scanning or deeplink handling.
+
+- QR Code Flow:
+
+When the `UserOperation` contains a `PreApprovalScreen.QR_SCAN`, the app should open the camera to scan the QR code before confirming the operation. Use the camera to scan the QR code containing the necessary data payload for the operation.
+
+- Deeplink Flow:
+
+When the app is launched via a deeplink, preserve the data from the deeplink and extract the relevant data. When operations are loaded compare the operation ID from the deeplink data to the operations within the app to find a match.
+
+- Assign TOTP and Type to the Operation
+  Once the QR code is scanned or match from the deeplink is found, create a `WMTProximityCheck` with:
+  - `totp`: The actual Time-Based One-Time Password.
+  - `type`: Set to `ProximityCheckType.QR_CODE` or `ProximityCheckType.DEEPLINK`.
+  - `timestampRequested`: The timestamp when the QR code was scanned (by default, it is created as the current timestamp when the object is instantiated).
+
+- Authorizing the ProximityCheck
+  When authorizing, the SDK will by default add `timestampSigned` to the `ProximityCheck` object. This timestamp indicates when the operation was signed.