cordova-digital-onboarding 1.0.1 → 1.2.0

package/docs/Verifying-User.md

@@ -1,14 +1,16 @@
-# Verifying user
+# Verifying the User
 
-If your PowerAuthSDK instance was activated with the `WDOActivationService`, it will be in the state that needs additional verification. Without such verification, it won't be able to properly sign requests.
+If your `PowerAuth` instance was activated via the `WDOActivationService`, it will be in the state that needs additional verification. Without such verification, it won't be able to properly sign requests.
 
-Additional verification means that the user will need to scan his face and documents like ID and/or passport.
+Additional verification requires the user to scan their face and provide documents such as an ID card or passport.
 
 ## When is the verification needed?
 
 Verification is needed if the `activationFlags` in the `PowerAuthActivationStatus` contains `VERIFICATION_PENDING` or `VERIFICATION_IN_PROGRESS` value.
 
+<!-- begin box info -->
 To simplify this check, you can use the `WDOVerificationService.isVerificationRequired` method that returns a boolean indicating whether verification is required.
+<!-- end -->
 
 Example:
 
@@ -42,73 +44,71 @@ The final flow (which screens come after another) is controlled by the backend.
 - The screen that should be displayed is driven by the state on the server "session".   
 - At the beginning of the verification process, you will call the status which will tell you what to display to the user and which function to call next.
 - Each API call returns a result and a next screen to display.
-- This repeats until the process is finished or an "endstate state" is presented which terminates the process.
+- This repeats until the process is finished or an "end state" is presented which terminates the process.
 
 ## Possible state values
 
-State is defined by the `WDOVerificationStateType` enum with the following possibilities:
+State is defined by the `WDOVerificationStateType` with the following possibilities:
 
 ```typescript
 /** Types of the verification state */
-declare enum WDOVerificationStateType {
-    /**
-     * Show the verification introduction screen where the user can start the activation.
-     *
-     * The next step should be calling the `consentGet()`.
+enum WDOVerificationStateType {
+    /** 
+     * Show the verification introduction screen where the user can start the activation. 
+     * 
+     * The next step should be calling the `start()`.
      */
     intro = "intro",
-    /**
-     * Show approve/cancel user consent.
-     *
-     * The content of the text depends on the server configuration and might be plain text or HTML.
-     *
-     * The next step should be calling the `consentApprove`.
-     */
-    consent = "consent",
     /**
      * Show document selection to the user. Which documents are available and how many
      * can the user select is up to your backend configuration.
-     *
+     * 
      * The next step should be calling the `documentsSetSelectedTypes`.
      */
     documentsToScanSelect = "documentsToScanSelect",
     /**
      * User should scan documents - display UI for the user to scan all necessary documents.
-     *
+     * 
      * The next step should be calling the `documentsSubmit`.
      */
     scanDocument = "scanDocument",
-    /**
+    /** 
      * The system is processing data - show loading with text hint from provided `WDOStatusCheckReason`.
-     *
+     * 
      * The next step should be calling the `status`.
      */
     processing = "processing",
-    /**
+    /** 
      * The user should be presented with a presence check.
      * Presence check is handled by third-party SDK based on the project setup.
-     *
+     * 
      * The next step should be calling the `presenceCheckInit` to start the check and `presenceCheckSubmit` to
      * mark it finished.  Note that these methods won't change the status and it's up to the app to handle the process of the presence check.
      */
     presenceCheck = "presenceCheck",
     /**
      * Show enter OTP screen with resend button.
-     *
+     * 
      * The next step should be calling the `verifyOTP` with user-entered OTP.
      * The OTP is usually SMS or email.
      */
     otp = "otp",
+    /**
+     * Show "finish activation" with PIN prompt screen.
+     * 
+     * The next step should be calling the `finishActivation` with user entered PIN.
+     */
+    finishActivation = "finishActivation",
     /**
      * Verification failed and can be restarted
-     *
+     * 
      * The next step should be calling the `restartVerification` or `cancelWholeProcess` based on
      * the user's decision if he wants to try it again or cancel the process.
      */
     failed = "failed",
     /**
      * Verification is canceled and the user needs to start again with a new PowerAuth activation.
-     *
+     * 
      * The next step should be calling the `PowerAuth.removeActivationLocal()` and starting activation from scratch.
      */
     endState = "endState",
@@ -119,6 +119,127 @@ declare enum WDOVerificationStateType {
 }
 ```
 
+Based on the type value, additional data is provided in the union type `WDOVerificationState`.
+
+Available data per state type:
+
+```typescript
+export type WDOVerificationState =
+    | WDOIntroState
+    | WDODocumentsToScanSelectState
+    | WDOScanDocumentState
+    | WDOProcessingState
+    | WDOPresenceCheckState
+    | WDOOtpState
+    | WDOFinishActivation
+    | WDOFailedState
+    | WDOEndStateState
+    | WDOSuccessState
+
+/** 
+ * Show the verification introduction screen where the user can start the activation. 
+ * 
+ * The next step should be calling the `start`.
+ */
+export interface WDOIntroState {
+    type: WDOVerificationStateType.intro,
+    /** Indicates whether the user consent is required to proceed */
+    consentRequired: boolean
+}
+
+/**
+ * Show document selection to the user. Which documents are available and how many
+ * can the user select is up to your backend configuration.
+ * 
+ * The next step should be calling the `documentsSetSelectedTypes`.
+ */
+export interface WDODocumentsToScanSelectState {
+    type: WDOVerificationStateType.documentsToScanSelect
+}
+
+/**
+ * User should scan documents - display UI for the user to scan all necessary documents.
+ * 
+ * The next step should be calling the `documentsSubmit`.
+ */
+export interface WDOScanDocumentState {
+    type: WDOVerificationStateType.scanDocument
+    /** Scanning process that helps with the document scanning */
+    process: WDOVerificationScanProcess
+}
+
+/** 
+ * The system is processing data - show loading with text hint from provided `WDOStatusCheckReason`.
+ * 
+ * The next step should be calling the `status`.
+ */
+export interface WDOProcessingState {
+    type: WDOVerificationStateType.processing
+    /** Reason for the current processing state */
+    item: WDOStatusCheckReason
+}
+
+/** 
+ * The user should be presented with a presence check.
+ * Presence check is handled by third-party SDK based on the project setup.
+ * 
+ * The next step should be calling the `presenceCheckInit` to start the check and `presenceCheckSubmit` to
+ * mark it finished.  Note that these methods won't change the status and it's up to the app to handle the process of the presence check.
+ */
+export interface WDOPresenceCheckState {
+    type: WDOVerificationStateType.presenceCheck
+}
+
+/**
+ * Show enter OTP screen with resend button.
+ * 
+ * The next step should be calling the `verifyOTP` with user-entered OTP.
+ * The OTP is usually SMS or email.
+ */
+export interface WDOOtpState {
+    type: WDOVerificationStateType.otp
+    /** Number of remaining attempts to enter the correct OTP */
+    remainingAttempts?: number
+}
+
+/**
+ * Show "finish activation" with PIN prompt screen.
+ * 
+ * The next step should be calling the `finishActivation` with user entered PIN.
+ */
+export interface WDOFinishActivation {
+    type: WDOVerificationStateType.finishActivation
+}
+
+/**
+ * Verification failed and can be restarted
+ * 
+ * The next step should be calling the `restartVerification` or `cancelWholeProcess` based on
+ * the user's decision if he wants to try it again or cancel the process.
+ */
+export interface WDOFailedState {
+    type: WDOVerificationStateType.failed
+}
+
+/**
+ * Verification is canceled and the user needs to start again with a new PowerAuth activation.
+ * 
+ * The next step should be calling the `PowerAuth.removeActivationLocal()` and starting activation from scratch.
+ */
+export interface WDOEndStateState {
+    type: WDOVerificationStateType.endState
+    /** Reason for the end state */
+    reason: WDOEndStateReason
+}
+
+/**
+ * Verification was successfully ended. Continue into your app flow.
+ */
+export interface WDOSuccessState {
+    type: WDOVerificationStateType.success
+}
+```
+
 ## Creating an instance
 
 To create an instance you will need a `PowerAuth` instance that is __already activated__.
@@ -130,11 +251,14 @@ To create an instance you will need a `PowerAuth` instance that is __already act
 
 Example:
 ```typescript
+// create and configure PowerAuth instance
 const powerAuth = new PowerAuth("my-pa-instance")
-powerAuth.configure({
+await powerAuth.configure({
     configuration: "ARCB+...jg==", // base64 PowerAuth configuration
     baseEndpointUrl: "https://my-server-deployment.com/enrollment-server/"
 })
+
+// create activation service
 const verification = new WDOVerificationService(
     powerAuth,
     "https://my-server-deployment.com/enrollment-server-onboarding/"
@@ -143,11 +267,11 @@ const verification = new WDOVerificationService(
 
 ## Getting the verification status
 
-When entering the verification flow for the first time (for example fresh app start), you need to retrieve the state of the verification.
+When starting the verification flow for the first time (such as after a fresh app launch), you should retrieve the current verification state.
 
-The same needs to be done after some operation fails and it's not sure what is the next step in the verification process.
+You should also retrieve the state after any operation fails, or whenever you are unsure about the next step in the verification process.
 
-Most verification functions return the result and also the state for your convenience of "what next".
+Most verification functions return both the result and the updated state, making it easier to determine what action to take next.
 
 Getting the state directly:
 
@@ -156,6 +280,12 @@ const verification: WDOVerificationService // configured instance
 try {
     const vfStatus = await verification.status()
     // handle `WDOVerificationState` state and navigate to the expected screen
+    if (vfStatus.type === WDOVerificationStateType.intro) {
+        // display intro screen
+    } else if (vfStatus.type === WDOVerificationStateType.documentsToScanSelect) {
+        // display document selector
+    }
+    // ... other states
 } catch (error) {
     if (error.verificationState) {
         // show expected screen based on the state
@@ -165,37 +295,26 @@ try {
 }
 ```
 
-## Getting the user consent text
+## Starting the identity verification
 
-When the state is `intro`, the first step in the flow is to get the context text for the user to approve.
+When the state is `intro`, the first step in the flow is to start the verification process by calling `start` function.
 
 ```typescript
+const state: WDOVerificationState // we're assuming that the state is `intro` here (WDOIntroState)
 const verification: WDOVerificationService // configured instance
 try {
-    const consentTextResponse = await verification.consentGet()
-    // state will be in the `consent` case here - display the consent screen
-} catch (error) {
-    if (error.verificationState) {
-        // show expected screen based on the state
+    let consentResult: WDOConsentResponse
+    const introState = state as WDOIntroState
+    if (introState.consentRequired) {
+        const consentTextResponse = await verification.consentGet()
+        // show consent screen to the user and get his approval
+        // assuming user approved the consent here
+        consentResult = WDOConsentResponse.approved
     } else {
-        // navigate to error screen
+        consentResult = WDOConsentResponse.notRequired
     }
-}
-```
-
-## Approving the user consent
-
-When the state is `consent`, you should display the consent text to the user to approve or reject.
-
-If the user __rejects the consent__, just return him to the intro screen, there's no API call for reject.
-
-If the user chooses to accept the consent, call `consentApprove` function. If successful, `documentsToScanSelect` state will be returned.
-
-```typescript
-const verification: WDOVerificationService // configured instance
-try {
-    const approvalResult = await verification.consentApprove()
-    // state will be in the `documentsToScanSelect` case here - display the document selector
+    const startResult = await verification.start(consentResult)
+    // process the returned state, should be `documentsToScanSelect` now
 } catch (error) {
     if (error.verificationState) {
         // show expected screen based on the state
@@ -207,13 +326,14 @@ try {
 
 ## Set document types to scan
 
-After the user approves the consent, present a document selector for documents which will be scanned. The number and types of documents (or other rules like 1 type required) are completely dependent on your backend system integration. You can retrieve the list of available document types from the [configuration service](Process-Configuration.md).
+After the user approves the consent, present a document selector for documents which will be scanned. The number and types of documents (or other rules like 1 type required) are completely dependent on your backend system integration. You can retrieve the list of available document types from the [configuration service](Process-Configuration.md) or have it hard-coded.
 
 For example, your system might require a national ID and one additional document like a driver's license, passport, or any other government-issued personal document.
 
 ```typescript
 const verification: WDOVerificationService // configured instance
 try {
+    // assuming user selected ID card and driver's license
     const docTypesResult = await verification.documentsSetSelectedTypes([
         WDODocumentType.idCard,
         WDODocumentType.driversLicense
@@ -236,7 +356,16 @@ This step does not move the state of the process but is a "stand-alone" API call
 
 Since the document scanning itself is not provided by this library but by a 3rd party library, some of them need a server-side initialization.
 
-If your chosen scanning SDK requires such a step, use this function to retrieve necessary data from the server.
+If your chosen "document scan SDK" requires such a step, use this function to retrieve necessary data from the server.
+
+Example:
+
+```typescript
+const verification: WDOVerificationService // configured instance
+const challengeFromSDK = "..." // optional challenge from the scanning SDK
+const initResult = await verification.documentsInitSDK(challengeFromSDK)
+// use the `initResult` to initialize the scanning SDK
+```
 
 ## Scanning a document
 
@@ -256,7 +385,7 @@ for your implementation.
 When a document is scanned (both sides when required), it needs to be uploaded to the server.
 
 <!-- begin box warning -->
-__Images of the document should not be bigger than 1MB. Files that are too big will take longer time to upload and process on the server.__
+__Images of the document should not be bigger than hundreds of kilobytes. Files that are too big will take longer time to upload and process on the server.__
 <!-- end -->
 
 To upload a document, use `documentsSubmit` function. Each side of a document is a single `WDODocumentFile` instance.
@@ -270,8 +399,8 @@ const passportToUpload = WDODocumentFile(
     "BASE64_ENCODED_IMAGE_DATA", // raw image data from the document scanning library/photo camera
     WDODocumentType.passport,
     WDODocumentSide.front, // passport has only front side
-    undefined, // use only when re-uploading the file (for example when first upload was rejected because of a blur)
-    undefined // optional, use when provided by the document scanning library
+    undefined, // original id, optional (use only when re-uploading the file - for example when first upload was rejected because of a blur)
+    undefined // signature, optional (use when provided by the document scanning library)
 )
 try {
     const result = await verification.documentsSubmit([passportToUpload])
@@ -363,6 +492,35 @@ try {
 }
 ```
 
+## Finalizing the verification (optional)
+
+When the state `finishActivation` is received, prompt the user for a PIN code. 
+
+This PIN code is then used to activate a new `PowerAuth` object that will be used for signing requests.
+
+Once the new `PowerAuth` instance is activated, the verification process is finished, and the user can proceed to the main app flow *with the new `PowerAuth` instance*.
+
+<!-- begin box info -->
+If the user's PIN used for the original activation should be equal to the one used for the new activation, then:
+- Set the `validatePassword` parameter to `true` in the `finishActivation` call. 
+- The `PowerAuthPassword` passed to the `finishActivation` needs to be reusable (`destroyOnUse` set to false - `new PowerAuthPassword(false)`).
+<!-- end -->
+
+Example:
+
+```typescript
+const verification: WDOVerificationService // configured instance
+const newPaInstance: PowerAuth // new PowerAuth instance to be activated and then used in the app
+try {
+    const password = await PowerAuthPassword.fromString("user-password", false) // reusable password
+    const finishResult = await verification.finishActivation(newPaInstance, "my-new-activation-name", password, true)
+    // When here, the newPaInstance is activated and ready to use (to sign requests and so on).
+    // The original PowerAuth instance used for the verification will be in the `REMOVED` state and the `verification` instance can't be used anymore.
+} catch (error) {
+    // handle error
+}
+```
+
 ## Success state
 
 When a whole verification is finished, you will receive the `success` state. Show a success screen and navigate the user to a common activated flow.

package/docs/_Sidebar.md

@@ -3,7 +3,7 @@
 - [SDK Integration](SDK-Integration.md)
 - [Process Configuration](Process-Configuration.md)
 - [Device Activation (With Weak Credentials)](Device-Activation.md)
-- [Verifying User With Document Scan And Genuine Presence Check](Verifying-User.md)
+- [Verifying the User](Verifying-User.md)
 - [Language Configuration](Language-Configuration.md)
 - [Logging](Logging.md)