Updated diagram and workings to final approved version of handling auth (#5)

* diagram added

* Implemented review suggestions:
* warning on how to respond errors
* changed from fakebackend to exampleBackend
* moved finishing of the session to the verify endpoint
* moved from "used" to "status", and now we reject or approve

* updated diagram

* correctly sending identityId to backend

* update diagram

* updated diagram with alts to clarify conditionals and actions on errors

Author: levhitaIncode

README.md

@@ -1,11 +1,12 @@
 # Face Authentication Validation Example
+
 This project demonstrates a secure face authentication flow using Incode's WebSDK with proper validation and session management. The application implements:
 
-- **User hint input** for authentication (customer ID, email, or phone)
+- **User hint input** for authentication (customerId, email, or phone)
 - **Face authentication** using Incode's renderAuthFace SDK
 - **Session management** with IndexedDB to prevent reuse
 - **Backend validation** to verify authentication integrity by:
-  - Matching candidate ID from the SDK with identity ID from the score API
+  - Matching candidate from the SDK with identityId from the score API
   - Validating overall authentication status
   - Preventing token tampering and session replay attacks
   - Marking sessions as used to prevent reuse
@@ -21,47 +22,71 @@ sequenceDiagram
     participant IncodeAPI
     participant IndexedDB
 
-    Note over Frontend: Enter hint:<br> email/phone/identityId
-    Frontend->>Backend: Start Session in Backend
+    Note over Frontend: Enter hint:<br> identityId
+    Note over Frontend: WebSDK: create()
+    Frontend->>Backend: Start Session in Backend<br>{identityId}
     Backend->>IncodeAPI: Create new session<br>{configurationId, apikey}
     Note over IncodeAPI: /omni/start
     IncodeAPI-->>Backend: Returns Session<br>{token, interviewId}
-    Backend->>IndexedDB: Store session<br>{key: interviewId, backToken: token, used: false)
+    Backend->>IndexedDB: Store session<br>{key: interviewId, backToken: token, status: pending, identityId)
     Backend-->>Frontend: Return Session<br>{token, interviewId}
-    
-    Note over Frontend: renderAuthFace(token, hint)
+
+    Note over Frontend: WebSDK: renderAuthFace(token, hint)
     Note over Frontend: User completes face authentication
-    Note over Frontend:Returns:<br>{candidateId}
-    
-    
-    Frontend->>Backend: Mark Session as Completed<br>{token}
-    Note over IncodeAPI: /0/omni/finish-status 
-    Backend->>IncodeAPI: Get finish status
-    IncodeAPI-->>Backend: Return:<br>{redirectionUrl, action}//Unused
-    
-    Frontend->>Backend: Validate Authentication<br>{interviewId, token, candidateId}
+    Note over Frontend:Returns:<br>{candidate}
+
+    Frontend->>Backend: Validate Authentication<br>{interviewId, token, candidate}
     Backend->>IndexedDB: Get Session Info:<br>{key:interviewId}
-    IndexedDB-->>Backend:  {backToken, used}
-    Note over Backend: Validate interviewId exists in DB
-    Note over Backend: Validate Session wasn't Used<br>used != True
-    Note over Backend: Validate tokens match<br>token === backToken
+    IndexedDB-->>Backend:  {backToken, status}
+    alt interviewId doesn't exist in DB
+      Backend->>Frontend: {"interviewId doesn't exists", valid:false}
+    end
+    alt status != pending
+      Backend->>Frontend: { "Session was already verified", valid:false}
+    end
+    alt candidate != session.identityId
+      Backend->>IndexedDB: Mark session as Rejected<br>{interviewId, status:rejected}
+      Backend->>Frontend: {"Stored identityId doesn't match candidate", valid:false}
+    end
+    alt token != backToken
+      Backend->>IndexedDB: Mark session as Rejected<br>{interviewId, status:rejected}
+      Backend->>Frontend: {"Stored token doesn't match token", valid:false}
+    end
+   
+    Backend->>IncodeAPI: Mark session as completed
+    Note over IncodeAPI: /0/omni/finish-status
+    IncodeAPI-->>Backend: Return:<br>{redirectionUrl, action}//Unused
+
     Backend->>IncodeAPI: Get Authentication Score<br>{token:backToken}
     Note over IncodeAPI: /0/omni/get/score
     IncodeAPI-->>Backend: {status, identityId}
-    Note over Backend: Validate candidateId matches identityId<br> candidateId === identityId
-    Note over Backend: Validate Score is OK:<br>status === "OK"
-    Backend->>IndexedDB: Mark session as used<br>{interviewId, used:true}
-    Backend-->>Frontend: Return validation result<br>{message, valid, identityId}
+    alt identityId != candidate
+      Backend->>IndexedDB: Mark session as Rejected<br>{interviewId, status:rejected}
+      Backend->>Frontend: {"candidate doesn't matches score identityId", valid:false}
+    end
+    alt score.status != "OK"
+      Backend->>IndexedDB: Mark session as Rejected<br>{interviewId, status:rejected}
+      Backend->>Frontend: {"Score for this session is not OK", valid:false}
+    end
+
+    Note over Backend: Success
+    Backend->>IndexedDB: Mark session as approved<br>{interviewId, status:approved}
+    Backend-->>Frontend: Return validation result<br>{"Succesful validation", valid:true, identityId}
     Note over Frontend: Show validation results
 ```
 
 # Requirements
+
 Vite requires Node.js version 14.18+, 16+. some templates require a higher Node.js version to work, please upgrade if your package manager warns about it.
 
 # Install
+
 Run `npm install`
+
 # Config
+
 Copy `.env.example` to `.env.local` and add your local values
+
 ```
 VITE_API_URL=https://demo-api.incodesmile.com/0
 VITE_SDK_URL=https://sdk.incode.com/sdk/onBoarding-1.80.1.js
@@ -71,11 +96,13 @@ VITE_FAKE_BACKEND_APIURL=https://demo-api.incodesmile.com
 VITE_FAKE_BACKEND_APIKEY=
 VITE_FAKE_BACKEND_FLOW_ID=
 ```
+
 Remember the Flow holds the backend counter part of the process, some configurations there might affect the behavior of the WebSDK here.
 
 # Fake Backend Server
+
 Starting and finishing the session must be done in the backend. To simplify development, this
-sample includes a `fake_backend.js` file that handles backend operations in the frontend. 
+sample includes a `fake_backend.js` file that handles backend operations in the frontend.
 
 **Important:** Replace this with a proper backend for production. The API key should NEVER be exposed in the frontend.
 
@@ -87,26 +114,28 @@ sample includes a `fake_backend.js` file that handles backend operations in the
 - `fakeBackendValidateAuthentication()` - Validates the authentication by:
   - Checking if the session exists and hasn't been used
   - Verifying the token matches the stored token
-  - Comparing candidate ID with identity ID from the score
+  - Comparing candidate with identityId from the score
   - Ensuring overall status is "OK"
   - Marking the session as used to prevent reuse
 
 # Run
+
 Vite is configured to serve the project using https and and expose him self, so you can easily test with your mobile phone on the local network.
 
 run `npm run dev`
 
 A new server will be exposed, the data will be in the terminal
 
 # Build
+
 run `npm run build`
 
 A new build will be created in `/dist` you can serve that build everywhere just remember to serve with https.
 
 # Testing especific versions of the webSDK locally
+
 You can save the specific version needed under `/public` and change the `VITE_SDK_URL` variable on `.env.local` to something like:
 
 ```
 VITE_SDK_URL=/name-of-the-js-file.js
 ```
-

fake_backend.js example_backend.jsfake_backend.js renamed to example_backend.js

@@ -8,9 +8,9 @@ const defaultHeader = {
   "api-version": "1.0",
 };
 
-// Call Incode's `omni/start` API to create an Incode session which will include a
+// Public: Call Incode's `omni/start` API to create an Incode session which will include a
 // token in the response.
-const fakeBackendStart = async function () {
+const start = async function (identityId) {
   const url = `${apiurl}/omni/start`;
   const params = {
     configurationId: flowid,
@@ -34,102 +34,134 @@ const fakeBackendStart = async function () {
   const { token, interviewId } = responseData;
 
   // Store session in local DB, session will be created as used: false.
-  await addSession(interviewId, token);
+  await addSession(interviewId, token, identityId);
 
   return { token, interviewId };
 };
 
-// Finishes the session started at /start
-const fakeBackendFinish = async function (token) {
-  const url = `${apiurl}/omni/finish-status`;
-
-  let sessionHeaders = { ...defaultHeader };
-  sessionHeaders["X-Incode-Hardware-Id"] = token;
-
-  let response;
-  try {
-    response = await fetch(url, { method: "GET", headers: sessionHeaders });
-    if (!response.ok) {
-      throw new Error("Request failed with code " + response.status);
-    }
-  } catch (e) {
-    throw new Error("HTTP Post Error: " + e.message);
-  }
-  const { redirectionUrl, action } = await response.json();
-  return { redirectionUrl, action };
-};
-
-const fakeBackendValidateAuthentication = async function (interviewId, token, candidateId) {
+// Public: Verify the authentication by checking the score and session data
+const verifyAuthentication = async function (interviewId, token, candidate) {
   const session = await getSession(interviewId);
 
+  // Prevents usage of session that doesn't exist.
   if (!session) {
     return {
+      // Detailed debug message, in production you might want to avoid exposing internal details.
       message: "No session found for interviewId " + interviewId,
       valid: false,
     };
   }
+  
   // Prevents reuse of the same session.
-  if (session.used) {
+  if (session.status !== "pending") {
     return {
+      // Detailed debug message, in production you might want to avoid exposing internal details.
       message: "Session already used for interviewId " + interviewId,
       valid: false,
     };
   }
 
   // Prevents usage of token from another interviewId.
   if (session.token !== token) {
+    // Mark the session as rejected.
+    await updateSession(interviewId, "rejected");
     return {
+      // Detailed debug message, in production you might want to avoid exposing internal details.
       message: "Token mismatch for interviewId " + interviewId,
       valid: false,
     };
   }
+
+  // Prevents usage of candidate that doesn't match the identityId stored in session.
+  if (session.identityId !== candidate) {
+    // Mark the session as rejected.
+    await updateSession(interviewId, "rejected");
+    return {
+      // Detailed debug message, in production you might want to avoid exposing internal details.
+      message: "identityId and candidate mismatch for interviewId " + interviewId,
+      valid: false,
+    };
+  }
+
+  // Finishing the session stop it from being changed further and triggers score calculation and business rules.
+  await finish(token); // Mark session as finished in Incode backend
 
   let identityId, scoreStatus;
   try {
     // At this point we already verified that the token matches, but
     // to be clear about our intentions, we use the token stored in the
-    // database to get the identityId and compare it with the candidateId.
-    const scoreResponse = await fakeBackendGetScore(session.token);
+    // database to get the identityId and compare it with the candidate.
+    const scoreResponse = await getScore(session.token);
     identityId = scoreResponse.authentication.identityId;
     scoreStatus = scoreResponse.overall.status;
   } catch (e) {
+    // Mark the session as rejected.
+    await updateSession(interviewId, "rejected");
     // If there is an error communicating with API, we consider validation failed.
     return {
+      // Detailed debug message, in production you might want to avoid exposing internal details.
       message: "Error validating authentication for interviewId " + interviewId + ": " + e.message,
       valid: false,
     };
   }
 
-  // renderFaceAuth returns candidateId, which should match identityId from score,
+  // renderFaceAuth returns candidate, which should match identityId from score,
   // this prevents tampering of the identityId in the frontend.
-  if (identityId !== candidateId) {
+  if (identityId !== candidate) {
+    // Mark the session as rejected.
+    await updateSession(interviewId, "rejected");
     return {
+      // Detailed debug message, in production you might want to avoid exposing internal details.
       message: "Session data doesn't match for interviewId " + interviewId,
       valid: false,
     };
   }
 
   // If backend score overall status is not OK, validation fails.
   if (scoreStatus !== "OK") {
+    // Mark the session as rejected.
+    await updateSession(interviewId, "rejected");
     return {
+      // Detailed debug message, in production you might want to avoid exposing internal details.
       message: "Face Validation failed for interviewId " + interviewId,
       valid: false,
     };
   }
 
-  // Mark session as used so it can't be used again
-  await markSessionAsUsed(interviewId);
+  // Mark the session as approved since all checks passed.
+  await updateSession(interviewId, "approved");
 
   // Only valid if all checks passed, we return the identityId that was validated.
   return {
+    // Detailed debug message, in production you might want to avoid exposing internal details.
     message: "Face Validation succeeded for interviewId " + interviewId,
     valid: true,
     identityId: identityId,
   };
 };
 
-// Finishes the session started at /start
-const fakeBackendGetScore = async function (token) {
+// Private: Calls Incode's `omni/finish-status` API mark the session as finished
+const finish = async function (token) {
+  const url = `${apiurl}/omni/finish-status`;
+
+  let sessionHeaders = { ...defaultHeader };
+  sessionHeaders["X-Incode-Hardware-Id"] = token;
+
+  let response;
+  try {
+    response = await fetch(url, { method: "GET", headers: sessionHeaders });
+    if (!response.ok) {
+      throw new Error("Request failed with code " + response.status);
+    }
+  } catch (e) {
+    throw new Error("HTTP Post Error: " + e.message);
+  }
+  const { redirectionUrl, action } = await response.json();
+  return { redirectionUrl, action };
+};
+
+// Private: Call Incode's `omni/get/score` API to retrieve the score for the session
+const getScore = async function (token) {
   const url = `${apiurl}/omni/get/score`;
 
   let sessionHeaders = { ...defaultHeader };
@@ -234,15 +266,16 @@ async function getSession(interviewId) {
 }
 
 // Add a new session to the database
-async function addSession(interviewId, token) {
+async function addSession(interviewId, token, identityId) {
   const db = await initDB();
   return new Promise((resolve, reject) => {
     const transaction = db.transaction([STORE_NAME], "readwrite");
     const objectStore = transaction.objectStore(STORE_NAME);
     const session = {
       interviewId,
       token,
-      used: false,
+      identityId,
+      status: "pending",
       timestamp: new Date().toISOString(),
     };
     const request = objectStore.add(session);
@@ -253,7 +286,12 @@ async function addSession(interviewId, token) {
 }
 
 // Update validation status for a session
-async function markSessionAsUsed(interviewId) {
+async function updateSession(interviewId, status) {
+  
+  if (status !== "rejected" && status !== "approved") {
+    throw new Error("Invalid status. Must be 'rejected' or 'approved'.");
+  }
+  
   const db = await initDB();
   return new Promise((resolve, reject) => {
     const transaction = db.transaction([STORE_NAME], "readwrite");
@@ -263,7 +301,7 @@ async function markSessionAsUsed(interviewId) {
     getRequest.onsuccess = () => {
       const session = getRequest.result;
       if (session) {
-        session.used = true;
+        session.status = status;
         const updateRequest = objectStore.put(session);
         updateRequest.onsuccess = () => resolve(session);
         updateRequest.onerror = () => reject(updateRequest.error);
@@ -275,4 +313,5 @@ async function markSessionAsUsed(interviewId) {
   });
 }
 
-export { fakeBackendStart, fakeBackendFinish, fakeBackendGetScore, fakeBackendValidateAuthentication };
+const exampleBackend = { start, verifyAuthentication }
+export default exampleBackend;

index.html

@@ -11,8 +11,8 @@
 <body>
   <main id="app">
     <div id="user-hint-container">
-      <label for="user-hint-input">User Hint (Customer ID, Email, or Phone):</label>
-      <input type="text" id="user-hint-input" placeholder="Enter customer ID, email, or phone" />
+      <label for="user-hint-input">User Hint (identityId):</label>
+      <input type="text" id="user-hint-input" placeholder="Enter identityId" />
       <button id="continue-btn">Continue</button>
     </div>
     <div id="camera-container"></div>