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

Author: levhitaIncode

README.md

@@ -1,11 +1,11 @@
 # 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
@@ -22,24 +22,25 @@ sequenceDiagram
     participant IndexedDB
 
     Note over Frontend: Enter hint:<br> email/phone/identityId
+    Note over Frontend: WebSDK: create()
     Frontend->>Backend: Start Session in Backend
     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-->>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}
+    Note over Frontend:Returns:<br>{candidate}
     
     
     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}
+    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
@@ -48,7 +49,7 @@ sequenceDiagram
     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 candidate matches identityId<br> candidate === 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}
@@ -87,7 +88,7 @@ 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
 

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: "Token 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>

main.js

@@ -1,8 +1,11 @@
-import { fakeBackendStart, fakeBackendFinish, fakeBackendValidateAuthentication } from "./fake_backend";
+/* main.js */
+
+/** Example Backend, this functions should be replaced with your actual backend implementation **/
+import exampleBackend from "./example_backend";
 
 let incodeSDKInstance;
 let incodeSession;
-let candidateId;
+let candidate;
 
 const cameraContainer = document.getElementById("camera-container");
 
@@ -22,7 +25,7 @@ async function authenticate() {
   const userHintDiv = document.getElementById("user-hint-container");
   userHintDiv.style.display = "none";
 
-  incodeSession = await fakeBackendStart();
+  incodeSession = await exampleBackend.start();
   renderAuthentication(hintInput.value);
 }
 
@@ -50,43 +53,39 @@ function finishAuthentication(response) {
     }
    */
 
-  candidateId = response.candidate; // Store candidate globally
+  candidate = response.candidate; // Store candidate globally
 
-  fakeBackendFinish(incodeSession.token)
-    .then((backendResponse) => {
-      console.log(backendResponse);
-      const container = document.getElementById("finish-container");
-      container.innerHTML = `
-        <h1>Authentication Finished</h1>
-        <p><strong>Overall Status:</strong> ${response.overallStatus}</p>
-        <p><strong>Candidate:</strong> ${response.candidate}</p>
+  const container = document.getElementById("finish-container");
+  container.innerHTML = `
+        <h1>Authentication Process Finished</h1>
+        <p><strong>Candidate:</strong> ${candidate}</p>
         <button id="verify-authentication-btn">Verify Authentication</button>
       `;
-      document.getElementById("verify-authentication-btn").addEventListener("click", verifyAuthentication);
-    })
-    .catch((e) => {
-      showError(e);
-    });
+  document.getElementById("verify-authentication-btn").addEventListener("click", verifyAuthentication);
 }
 
 // 4.- Verify the authentication against the score
 async function verifyAuthentication() {
-  console.log("Verifying authentication for candidateId:", candidateId);
+  console.log("Verifying authentication for candidate:", candidate);
   try {
-    const validationResult = await fakeBackendValidateAuthentication(incodeSession.interviewId, incodeSession.token, candidateId);
+    const validationResult = await exampleBackend.verifyAuthentication(
+      incodeSession.interviewId,
+      incodeSession.token,
+      candidate,
+    );
     console.log("Validation result:", validationResult);
 
     const container = document.getElementById("finish-container");
     container.innerHTML += `
       <hr>
       <h2>Authentication Verification</h2>
       <p><strong>Interview ID:</strong> ${incodeSession.interviewId}</p>
-      <p><strong>Candidate ID:</strong> ${candidateId}</p>
-      <p><strong>Identity ID:</strong> ${validationResult.identityId || 'N/A'}</p>
+      <p><strong>Candidate:</strong> ${candidate}</p>
+      <p><strong>Identity ID:</strong> ${validationResult.identityId || "N/A"}</p>
       <p><strong>Message:</strong> ${validationResult.message}</p>
       <p><strong>Authentication Valid:</strong> <span style="color: ${validationResult.valid ? "green" : "red"}; font-weight: bold;">${
-      validationResult.valid ? "✓ VALID" : "✗ INVALID"
-    }</span></p>
+        validationResult.valid ? "✓ VALID" : "✗ INVALID"
+      }</span></p>
     `;
     document.getElementById("verify-authentication-btn").addEventListener("click", verifyAuthentication);
   } catch (e) {