verant_id_cloud_scan 1.4.5-beta.1 → 1.4.5-beta.11

package/Api.js

@@ -3,17 +3,110 @@ import { formatDateToISO, DATE_FIELDS } from "./DateUtils.js";
 import { FIELD_MAPPING, FIELD_DEFAULTS, getFieldValue } from "./FieldMapping.js";
 import { sanitizeFieldForDmv } from "./FormatUtils.js";
 
-//prod
-const licenseServerAddress = "https://lic.verantid.com/api/v1";
-const dmvServerAddress = "https://dmv.verantid.com/api/v1/dmv_check";
-// staging
-// const licenseServerAddress =
-//   "https://verant-license-server-staging-52b03b060a98.herokuapp.com/api/v1";
-// const dmvServerAddress =
-//   "https://dmv-check-server-staging-fcaab48bec21.herokuapp.com/api/v1/dmv_check";
+/**
+ * Environment Detection & Management
+ *
+ * Defaults to PRODUCTION for all hosts (including localhost).
+ * Only verify-staging.verantid.com automatically uses staging.
+ * Host apps can explicitly override via setEnvironment('staging' | 'production').
+ */
+
+// Current environment - starts as null to trigger detection on first use
+let currentEnvironment = null;
+
+/**
+ * Detect environment based on hostname
+ * @returns {'staging' | 'production'}
+ */
+function detectEnvironment() {
+  // Default to production for all hosts
+  let environment = 'production';
+
+  // Only auto-switch to staging for VerantID's staging domain
+  if (typeof window !== 'undefined') {
+    const hostname = window.location.hostname;
+
+    // ONLY verify-staging.verantid.com uses staging by default
+    if (hostname === 'verify-staging.verantid.com') {
+      environment = 'staging';
+    }
+
+    // All other hostnames (localhost, customer sites, verify.verantid.com, etc.) use production
+  }
+
+  console.log('[CloudScan] Environment detected:', environment, 'on', typeof window !== 'undefined' ? window.location.hostname : 'server');
+  return environment;
+}
+
+/**
+ * Get current environment (detects if not already set)
+ * @returns {'staging' | 'production'}
+ */
+function getEnvironment() {
+  if (currentEnvironment === null) {
+    currentEnvironment = detectEnvironment();
+  }
+  return currentEnvironment;
+}
+
+/**
+ * Explicitly set the environment
+ * @param {'staging' | 'production'} environment
+ * @throws {Error} If environment is not 'staging' or 'production'
+ */
+export function setEnvironment(environment) {
+  if (environment !== 'staging' && environment !== 'production') {
+    throw new Error(`Invalid environment: "${environment}". Must be "staging" or "production".`);
+  }
+  currentEnvironment = environment;
+}
+
+/**
+ * Get license server address based on current environment
+ * @returns {string}
+ */
+function getLicenseServerAddress() {
+  const env = getEnvironment();
+  return env === 'staging'
+    ? "https://lic-staging.verantid.com/api/v1"
+    : "https://lic.verantid.com/api/v1";
+}
+
+/**
+ * Get DMV server address based on current environment
+ * @returns {string}
+ */
+function getDmvServerAddress() {
+  const env = getEnvironment();
+  return env === 'staging'
+    ? "https://dmv-check-server-staging-fcaab48bec21.herokuapp.com/api/v1/dmv_check"
+    : "https://dmv.verantid.com/api/v1/dmv_check";
+}
+
+/**
+ * Get Face Comparison server address based on current environment
+ * @returns {string}
+ */
+export function getFaceComparisonServerAddress() {
+  const env = getEnvironment();
+  return env === 'staging'
+    ? "https://staging.face.verantid.bluerocket.us/compare_id_and_face"
+    : "https://faceid.verantid.com/compare_id_and_face";
+}
+
+/**
+ * Get Mobile Verification server address based on current environment
+ * @returns {string}
+ */
+function getMobileVerificationServerAddress() {
+  const env = getEnvironment();
+  return env === 'staging'
+    ? "https://staging.mdl.verantid.bluerocket.us"
+    : "https://mdl.verantid.bluerocket.us";
+}
 
 export const dmvCheck = async (clientId, scannerType, licenseData) => {
-  const url = dmvServerAddress;
+  const url = getDmvServerAddress();
 
   // Build the driver object dynamically.
   const driver = {};
@@ -104,7 +197,7 @@ export const dmvCheck = async (clientId, scannerType, licenseData) => {
 };
 
 export const checkDmvFeatureLicense = async (clientId) => {
-  const url = licenseServerAddress + "/dmv_verifications/check_license";
+  const url = getLicenseServerAddress() + "/dmv_verifications/check_license";
   const data = { client_id: clientId };
 
   try {
@@ -138,7 +231,7 @@ export const checkDmvFeatureLicense = async (clientId) => {
 };
 
 export const checkFaceComparisonFeatureLicense = async (clientId) => {
-  const url = licenseServerAddress + "/facial_scans/check_license";
+  const url = getLicenseServerAddress() + "/facial_scans/check_license";
   const data = { client_id: clientId };
 
   try {
@@ -171,9 +264,26 @@ export const checkFaceComparisonFeatureLicense = async (clientId) => {
   }
 }
 
-export const checkLicense = async (clientId, macAddress) => {
-  const url = licenseServerAddress + "/check_license";
-  const data = { client_id: clientId, mac_address: macAddress };
+// Pass exactly one of macAddress / serialNumber. The license server rejects
+// requests that supply both or neither; we also fail fast here so callers
+// don't have to wait for a 400 to learn they passed a bad identifier.
+export const checkLicense = async (clientId, identifier = {}) => {
+  if (identifier === null || typeof identifier !== "object") {
+    throw new TypeError(
+      `checkLicense: second argument must be an object like { macAddress } or { serialNumber }, got ${typeof identifier}`,
+    );
+  }
+  const { macAddress, serialNumber } = identifier;
+  if (Boolean(macAddress) === Boolean(serialNumber)) {
+    throw new Error(
+      "checkLicense: pass exactly one of macAddress / serialNumber",
+    );
+  }
+
+  const url = getLicenseServerAddress() + "/check_license";
+  const data = { client_id: clientId };
+  if (macAddress) data.mac_address = macAddress;
+  if (serialNumber) data.serial_number = serialNumber;
 
   try {
     const response = await fetch(url, {
@@ -207,7 +317,7 @@ export const checkLicense = async (clientId, macAddress) => {
  * @returns {Promise<boolean>} True if autoDmv is enabled
  */
 export const checkAutoDmvEnabled = async (clientId) => {
-    const url = licenseServerAddress + "/check_feature_license";
+    const url = getLicenseServerAddress() + "/check_feature_license";
     const data = { client_id: clientId };
 
     try {
@@ -232,7 +342,7 @@ export const checkAutoDmvEnabled = async (clientId) => {
     }
   };
 export const getBarcodeLicenseKey = async () => {
-  const url = licenseServerAddress + "/get_barcode_license_key";
+  const url = getLicenseServerAddress() + "/get_barcode_license_key";
 
   try {
     const response = await fetch(url, {
@@ -253,45 +363,148 @@ export const getBarcodeLicenseKey = async () => {
   }
 };
 
-// Helper function for making POST requests to the scanner API
-const postToScannerApi = async (
+/**
+ * Build the /securelink URL for the given scanner address.
+ *
+ * Mirrors the SDK's historical behaviour: if the caller didn't include a
+ * scheme, default to http://. The scheme test is case-insensitive per
+ * RFC 3986 (VNT-1522) — `HTTP://`, `HTTPS://`, and mixed-case forms are
+ * recognised so the SDK doesn't double-prefix them with another `http://`.
+ */
+export const buildSecurelinkUrl = (scannerAddress) => {
+  const hasScheme = /^https?:\/\//i.test(scannerAddress);
+  const withScheme = hasScheme ? scannerAddress : `http://${scannerAddress}`;
+  return `${withScheme.replace(/\/+$/, "")}/securelink`;
+};
+
+/**
+ * Lower-level POST that returns a structured result instead of throwing.
+ * Used by `checkScannerPresentDetailed` (VNT-1522) so the caller can
+ * distinguish network failures, HTTP errors, parse failures, and scanner
+ * application-layer errors. Existing callers go through `postToScannerApi`
+ * which preserves the throw-on-error contract.
+ *
+ * Supports an external `AbortSignal` so host apps can cancel an in-flight
+ * probe on retry / unmount without waiting for the internal timeout.
+ *
+ * @param {string} scannerAddress
+ * @param {object} commandObj
+ * @param {number} [timeout=10000] timeout in ms before the internal AbortController aborts
+ * @param {AbortSignal} [externalSignal] optional external signal; when aborted, the request is cancelled
+ * @returns {Promise<{
+ *   threw: boolean,
+ *   error?: Error,
+ *   ok?: boolean,
+ *   status?: number,
+ *   statusText?: string,
+ *   body?: unknown,
+ *   attemptedUrl: string,
+ * }>}
+ */
+const postToScannerApiDetailed = async (
   scannerAddress,
   commandObj,
-  timeout = 10000
+  timeout = 10000,
+  externalSignal,
 ) => {
-  // Ensure the scanner address has a protocol (http:// or https://)
-  let formattedAddress = scannerAddress;
-  if (!scannerAddress.startsWith('http://') && !scannerAddress.startsWith('https://')) {
-    formattedAddress = `http://${scannerAddress}`;
-  }
-
-  let apiAddress = `${formattedAddress}/securelink`;
+  const attemptedUrl = buildSecurelinkUrl(scannerAddress);
 
   const controller = new AbortController();
-  const signal = controller.signal;
-
-  const fetchTimeout = setTimeout(() => {
-    controller.abort();
-  }, timeout);
+  const fetchTimeout = setTimeout(() => controller.abort(), timeout);
+
+  // Forward an external abort signal to our controller so the host app's
+  // cancellation (retry, unmount) propagates to the in-flight fetch.
+  let externalAbortHandler;
+  if (externalSignal) {
+    if (externalSignal.aborted) {
+      controller.abort();
+    } else {
+      externalAbortHandler = () => controller.abort();
+      externalSignal.addEventListener("abort", externalAbortHandler, { once: true });
+    }
+  }
 
   try {
-    const response = await fetch(apiAddress, {
+    const response = await fetch(attemptedUrl, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(commandObj),
-      signal: signal,
+      signal: controller.signal,
     });
 
-    clearTimeout(fetchTimeout);
+    // Read the body once as text, then try to JSON-parse — keeps a malformed
+    // body from making us discard otherwise-useful status info.
+    let body = null;
+    try {
+      const text = await response.text();
+      if (text) {
+        try {
+          body = JSON.parse(text);
+        } catch {
+          body = text; // not JSON, but still meaningful for diagnostics
+        }
+      }
+    } catch {
+      // body read failed — leave body=null, caller can decide
+    }
 
-    if (!response.ok) throw new Error(response.statusText);
-    return response.json();
+    return {
+      threw: false,
+      ok: response.ok,
+      status: response.status,
+      statusText: response.statusText,
+      body,
+      attemptedUrl,
+    };
   } catch (error) {
-    if (error.name === "AbortError") {
+    return { threw: true, error, attemptedUrl };
+  } finally {
+    clearTimeout(fetchTimeout);
+    if (externalSignal && externalAbortHandler) {
+      externalSignal.removeEventListener("abort", externalAbortHandler);
+    }
+  }
+};
+
+// Helper function for making POST requests to the scanner API. Thin wrapper
+// around `postToScannerApiDetailed` that preserves the historical contract
+// (throws on timeout / network / non-2xx; returns parsed JSON on success).
+const postToScannerApi = async (
+  scannerAddress,
+  commandObj,
+  timeout = 10000
+) => {
+  const result = await postToScannerApiDetailed(
+    scannerAddress,
+    commandObj,
+    timeout,
+  );
+
+  if (result.threw) {
+    if (result.error?.name === "AbortError") {
       throw new Error("Request timed out");
     }
-    throw error;
+    throw result.error;
+  }
+
+  if (!result.ok) {
+    throw new Error(result.statusText || `HTTP ${result.status}`);
+  }
+
+  // Match the original `response.json()` contract: throw if the 2xx body
+  // wasn't a parseable JSON object. The detailed wrapper deliberately
+  // preserves non-JSON bodies as strings (or `null` for empty) so error
+  // surfaces like `checkScannerPresentDetailed` can use them — but every
+  // existing caller of `postToScannerApi` (`getNetworkInfo`,
+  // `establishConnection`, `getParams`, `resetParams`, `setParameters`,
+  // `scanDocument`, …) reads object properties off the return value, so
+  // returning a string or null here would silently produce `undefined`
+  // downstream instead of failing loudly.
+  if (result.body === null || typeof result.body !== "object") {
+    throw new SyntaxError("Scanner response was not a JSON object");
   }
+
+  return result.body;
 };
 
 export const getNetworkInfo = (scannerAddress, commandObj) =>
@@ -318,40 +531,239 @@ export const stopScanning = (scannerAddress, commandObj) =>
 export const closeConnection = (scannerAddress, commandObj) =>
   postToScannerApi(scannerAddress, commandObj);
 
-// Check if scanner is present by attempting to connect and disconnect
-export const checkScannerPresent = async (scannerAddress) => {
-  try {
-    // Generate a unique message ID for this check
-    const messageId = new Date().toISOString();
-
-    // Attempt to establish connection
-    const connectCommand = {
-      Command: "Connect",
-      MessageId: messageId,
-      Exclusive: "false", // Use non-exclusive mode for just checking
-      IdleTimeout: "5",
+/**
+ * Classify a thrown fetch error into one of the documented codes (VNT-1522).
+ *
+ * `externallyAborted` distinguishes a host-app cancellation (retry, unmount)
+ * from an internal timeout — both surface as `AbortError` from fetch, but
+ * callers branching on `code` for UI copy (e.g. "scanner timed out") should
+ * not see the timeout label when the user themselves cancelled.
+ *
+ * @param {unknown} error
+ * @param {string} attemptedUrl
+ * @param {boolean} [externallyAborted=false]
+ * @returns {{ code: string, name: string, message: string, attemptedUrl: string }}
+ */
+const classifyFetchError = (error, attemptedUrl, externallyAborted = false) => {
+  if (error?.name === "AbortError") {
+    return {
+      code: externallyAborted ? "ABORTED" : "TIMEOUT",
+      name: "AbortError",
+      message: externallyAborted ? "Request aborted" : "Request timed out",
+      attemptedUrl,
+    };
+  }
+  if (error instanceof TypeError) {
+    // Browser fetch surfaces network failures (DNS, connection refused,
+    // mixed-content blocks, CORS preflight rejection) as `TypeError`.
+    return {
+      code: "NETWORK_ERROR",
+      name: "TypeError",
+      message: error.message || "Network error",
+      attemptedUrl,
     };
+  }
+  return {
+    code: "NETWORK_ERROR",
+    name: error?.name || "Unknown",
+    message: error?.message || String(error),
+    attemptedUrl,
+  };
+};
 
-    const connectResponse = await postToScannerApi(scannerAddress, connectCommand, 5000);
+/**
+ * Structured version of `checkScannerPresent` (VNT-1522).
+ *
+ * Returns `{ ok: true }` on success or `{ ok: false, error }` with a tagged
+ * `error.code` so host apps can distinguish:
+ *  - `TIMEOUT` — internal 5s timeout fired
+ *  - `ABORTED` — host app cancelled via the external `AbortSignal`
+ *  - `NETWORK_ERROR` — fetch threw (DNS, refused, mixed content, CORS, etc.)
+ *  - `HTTP_ERROR` — server replied non-2xx
+ *  - `INVALID_RESPONSE` — 2xx but the body wasn't JSON
+ *  - `SCANNER_ERROR` — 2xx JSON but no `SessionId` (the scanner returned
+ *    an application-layer error in the body, e.g. an HTTPS-only scanner
+ *    rejecting an HTTP probe with `{HttpRC:"403", ExtInformation:"..."}`)
+ *
+ * The error object also carries `attemptedUrl`, `status` (when a response
+ * was received), and the raw `scannerResponse` body for SCANNER_ERROR so
+ * callers can surface vendor-specific fields like `ExtInformation`.
+ *
+ * @param {string} scannerAddress
+ * @param {{ signal?: AbortSignal }} [options]
+ */
+export const checkScannerPresentDetailed = async (
+  scannerAddress,
+  options = {},
+) => {
+  const { signal } = options;
+  const attemptedUrl = buildSecurelinkUrl(scannerAddress);
+
+  const connectCommand = {
+    Command: "Connect",
+    MessageId: new Date().toISOString(),
+    Exclusive: "false", // non-exclusive — we're only probing
+    IdleTimeout: "5",
+  };
 
-    // If connection failed or no session ID, scanner not present
-    if (!connectResponse || !connectResponse.SessionId) {
-      return false;
-    }
+  const probe = await postToScannerApiDetailed(
+    scannerAddress,
+    connectCommand,
+    5000,
+    signal,
+  );
+
+  if (probe.threw) {
+    return {
+      ok: false,
+      error: classifyFetchError(
+        probe.error,
+        attemptedUrl,
+        Boolean(signal?.aborted),
+      ),
+    };
+  }
 
-    // Got a session ID, now disconnect
-    const disconnectCommand = {
-      Command: "Disconnect",
-      MessageId: new Date().toISOString(),
-      SessionId: connectResponse.SessionId,
+  if (!probe.ok) {
+    return {
+      ok: false,
+      error: {
+        code: "HTTP_ERROR",
+        name: "HTTPError",
+        message: probe.statusText || `HTTP ${probe.status}`,
+        status: probe.status,
+        attemptedUrl,
+      },
     };
+  }
 
-    await postToScannerApi(scannerAddress, disconnectCommand, 5000);
+  if (!probe.body || typeof probe.body !== "object") {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_RESPONSE",
+        name: "InvalidResponse",
+        message: "Scanner returned a non-JSON or empty body",
+        status: probe.status,
+        attemptedUrl,
+      },
+    };
+  }
+
+  if (!probe.body.SessionId) {
+    // App-layer scanner error — common when an HTTPS-only scanner is hit
+    // over HTTP. The body usually contains vendor-specific fields like
+    // `ExtInformation` ("Scanner not configured for HTTP") that we forward
+    // so callers can present an actionable message.
+    return {
+      ok: false,
+      error: {
+        code: "SCANNER_ERROR",
+        name: "ScannerError",
+        message:
+          probe.body.ExtInformation ||
+          probe.body.ErrorInformation ||
+          "Scanner returned no SessionId",
+        status:
+          typeof probe.body.HttpRC === "string"
+            ? parseInt(probe.body.HttpRC, 10) || probe.status
+            : probe.status,
+        attemptedUrl,
+        scannerResponse: probe.body,
+      },
+    };
+  }
+
+  // Got a SessionId — clean up by disconnecting. We don't surface a
+  // disconnect failure: from the host app's perspective the scanner IS
+  // present and the leaked session will time out server-side per the
+  // scanner's IdleTimeout.
+  const disconnectCommand = {
+    Command: "Disconnect",
+    MessageId: new Date().toISOString(),
+    SessionId: probe.body.SessionId,
+  };
+  await postToScannerApiDetailed(
+    scannerAddress,
+    disconnectCommand,
+    5000,
+    signal,
+  );
+
+  return { ok: true };
+};
+
+// Boolean form of scanner presence check. Thin wrapper around
+// `checkScannerPresentDetailed` (VNT-1522) — preserved for existing
+// callers; new code should prefer the detailed version.
+export const checkScannerPresent = async (scannerAddress) => {
+  const result = await checkScannerPresentDetailed(scannerAddress);
+  return result.ok;
+};
+
+/**
+ * Create a verification session for mobile ID verification
+ *
+ * POST /sessions
+ * Returns: session_id, session_url (for QR code), websocket_url (for real-time updates)
+ *
+ * @param {string} userId - User ID for the verification session
+ * @param {string} clientId - Client ID for licensing and tracking
+ * @param {string} [origin] - Holder page origin; binds the server's
+ *   SessionTranscript to the wallet's view (HPKE info). Required on non-default hosts.
+ * @returns {Promise<Object>} Session data with session_id, session_url, and websocket_url
+ */
+export const createVerificationSession = async (userId, clientId, origin) => {
+  const url = getMobileVerificationServerAddress() + "/sessions";
+  const data = { user_id: userId, client_id: clientId };
+  if (origin) {
+    data.origin = origin;
+  }
 
-    // Successfully connected and disconnected
-    return true;
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (response.ok) {
+      const responseData = await response.json();
+      return responseData;
+    } else {
+      // Read the body once as text — fetch consumes the stream on first read,
+      // so a `response.json()` then `response.text()` fallback would throw
+      // `TypeError: body stream already read` and mask the original error.
+      const errorText = await response.text();
+      let errorData = null;
+      try {
+        errorData = JSON.parse(errorText);
+      } catch {
+        // Non-JSON body (e.g. plain text 502 from API Gateway).
+      }
+
+      if (errorData) {
+        console.error("Verification session creation failed:", errorData);
+        return {
+          status: 'error',
+          message: errorData.message || 'Failed to create verification session',
+          error: errorData,
+        };
+      }
+      console.error("Verification session creation failed:", errorText);
+      return {
+        status: 'error',
+        message: 'Failed to create verification session',
+        raw_error: errorText,
+      };
+    }
   } catch (error) {
-    // Any error means scanner is not reachable
-    return false;
+    console.error("There was a problem with the verification session request:", error);
+    return {
+      status: 'error',
+      message: error.message || 'Unable to connect to verification service.'
+    };
   }
 };