verant_id_cloud_scan 1.4.4 → 1.4.5-beta.10

package/Api.js

@@ -1,18 +1,112 @@
 import { compressAndCompareImages } from "./FaceComparison.js";
 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; // make sure dmvServerAddress is defined elsewhere
+  const url = getDmvServerAddress();
 
   // Build the driver object dynamically.
   const driver = {};
@@ -36,16 +130,8 @@ export const dmvCheck = async (clientId, scannerType, licenseData) => {
       value = formatDateToISO(value);
     }
 
-    // Convert sex_code from M/F to 1/2 for AAMVA compliance
-    if (fieldName === 'sex_code' && value) {
-      const sexStr = String(value).trim().toUpperCase();
-      if (sexStr === 'M' || sexStr === 'MALE') {
-        value = '1';
-      } else if (sexStr === 'F' || sexStr === 'FEMALE') {
-        value = '2';
-      }
-      // If already 1 or 2, keep as is
-    }
+    // Sanitize field value for DMV/AAMVA submission
+    value = sanitizeFieldForDmv(fieldName, value);
 
     driver[fieldName] = value;
   });
@@ -111,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 {
@@ -145,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 {
@@ -179,7 +265,7 @@ export const checkFaceComparisonFeatureLicense = async (clientId) => {
 }
 
 export const checkLicense = async (clientId, macAddress) => {
-  const url = licenseServerAddress + "/check_license";
+  const url = getLicenseServerAddress() + "/check_license";
   const data = { client_id: clientId, mac_address: macAddress };
 
   try {
@@ -214,7 +300,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 {
@@ -239,7 +325,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, {
@@ -272,6 +358,9 @@ const postToScannerApi = async (
     formattedAddress = `http://${scannerAddress}`;
   }
 
+  // Remove trailing slash to prevent double slashes in URL
+  formattedAddress = formattedAddress.replace(/\/+$/, '');
+
   let apiAddress = `${formattedAddress}/securelink`;
 
   const controller = new AbortController();
@@ -362,3 +451,70 @@ export const checkScannerPresent = async (scannerAddress) => {
     return false;
   }
 };
+
+/**
+ * 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;
+  }
+
+  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) {
+    console.error("There was a problem with the verification session request:", error);
+    return {
+      status: 'error',
+      message: error.message || 'Unable to connect to verification service.'
+    };
+  }
+};

package/CHANGELOG.md

@@ -0,0 +1,198 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.5-beta.10] - 2026-05-11
+
+### Fixed
+- iOS HPKE decryption failure on non-default hosts (e.g. ngrok tunnels,
+  custom staging domains). `startMobileVerification()` now derives the
+  holder page origin from `mobileVerifyBaseUrl` (falling back to the
+  CSR page's `window.location.origin` for same-origin dev setups) and
+  forwards it to `POST /sessions`. The backend uses this origin to
+  build its SessionTranscript, which must match the origin the mobile
+  wallet binds to. Without it, the server fell back to a per-environment
+  default that disagreed with the wallet's view, causing
+  `"Decryption failed: Could not decrypt credential response"` (400).
+- `WebSocketClient.connect()` no longer hangs forever when the underlying
+  socket emits `onerror` or `onclose` before `onopen`. The returned Promise
+  now rejects with a tagged error in those paths so awaiters can handle
+  connection failures instead of waiting indefinitely.
+- `startMobileVerification()` QR code URL construction now uses `new URL()`
+  to safely combine `mobileVerifyBaseUrl` with the session id. Previously,
+  a base URL containing a query string or hash (e.g. `https://host/path?x=1`)
+  produced an invalid result like `https://host/path?x=1/{session_id}`.
+- `createVerificationSession()` no longer throws "body stream already
+  read" when an error response is not valid JSON. The response body is
+  now read once as text, then parsed in a try/catch instead of using
+  `response.json()` followed by a `response.text()` fallback.
+- `startMobileVerification()` no longer emits duplicate `onError`
+  callbacks when a WebSocket failure surfaces via both
+  `WebSocketClient.connect()` and the outer catch. Errors already
+  reported by a lower layer carry an `error.reported` flag, and the
+  outer catch skips re-emitting in that case.
+- `WebSocketClient.connect()` now invokes `callbacks.onError` from the
+  close-before-open path (previously only `onerror` did). Direct
+  `connectToVerificationSession` callers receive the failure event
+  even when no preceding `onerror` fires (e.g., server closes the
+  socket immediately). The synthesized error carries `reported: true`
+  so `startMobileVerification`'s outer catch still avoids double-emit.
+- `WebSocketClient._handleMessage()` no longer logs the raw WebSocket
+  frame to the console. Verification payloads carry PII (mDL fields,
+  portrait base64), so the raw `console.log` of `data` was dropped.
+  Per-route type logs below remain for debug visibility.
+- `WebSocketClient.connect()` now releases its socket reference when
+  `onerror` fires before `onopen`, so callers can immediately retry
+  `connect()` without hitting "WebSocket connection already exists"
+  in implementations where `onclose` doesn't fire after `onerror`.
+- `WebSocketClient` now transitions to the `ERROR` state (not
+  `CLOSED`) when the socket closes before opening, so
+  `status`/`onStatusChange` reflect a connection failure rather than
+  a normal disconnect. Post-open closes still transition to `CLOSED`.
+  Now driven by an explicit `hasOpened` flag (set in `onopen`) — the
+  previous version used the Promise's `settled` flag, which is also
+  set by pre-open `onerror` and would incorrectly downgrade the
+  ERROR state to CLOSED when the follow-up onclose fired.
+- `WebSocketClient.connect()` synchronous-throw rejections now carry
+  a stable `.code` (`NO_WEBSOCKET_IMPL` when the Node fallback fails,
+  `CONNECTION_FAILED` when the `WebSocket` constructor throws). The
+  thrown/rejected error now matches the structured `onError` payload,
+  so awaiters of the Promise can branch on the failure reason without
+  relying on the `onError` callback.
+- `WebSocketClient.disconnect()` called while the socket is still
+  CONNECTING no longer reports a spurious connection error. The
+  `onclose` triggered by the user-initiated close used to flip
+  `status` from `closed` back to `error` and emit `onError`; it now
+  detects an instance-level `_closeRequested` flag set by
+  `disconnect()` and skips both. The pending `connect()` Promise
+  rejects with `code: 'CLIENT_DISCONNECTED'` so awaiters resolve.
+- `WebSocketClient._handleMessage()` now decodes binary WebSocket
+  frames (Node `Buffer` from the `ws` package, browser `ArrayBuffer`
+  / `Uint8Array` when `binaryType === 'arraybuffer'`) via `TextDecoder`
+  before `JSON.parse`. Previously, anything that wasn't a string
+  passed through as-is, so `routeKey` was always undefined and every
+  frame was silently dropped as "Unknown message route."
+- Removed informational `console.log` calls from the mobile
+  verification code path (`WebSocketClient` + `startMobileVerification`).
+  Several of them embedded the `session_id` or QR target URL, which
+  is effectively a session access token and shouldn't be sent to
+  application logs / monitoring. Diagnostic `console.warn` and
+  `console.error` calls are preserved.
+
+### Changed
+- `startMobileVerification()` error callbacks now emit stage-specific
+  codes — `SESSION_CREATION_FAILED`, `QR_GENERATION_FAILED`, or
+  `WEBSOCKET_CONNECTION_FAILED` — so callers can distinguish which step
+  failed. Upstream `error.code` values are preserved when present.
+
+### Internal
+- The internal `createVerificationSession()` API helper gained an
+  optional third `origin` parameter; `startMobileVerification()` now
+  populates it from `mobileVerifyBaseUrl` (or `window.location.origin`
+  for same-origin dev). Host apps don't need to change anything — keep
+  calling `startMobileVerification()` as before.
+- `package.json` now declares a `"browser": { "ws": false }` field so
+  browser bundlers (Vite / Webpack / Rollup) stub out the Node-only
+  `ws` optional dependency instead of trying to bundle it. Has no
+  effect in Node — the dynamic `import('ws')` fallback still works.
+
+## [1.4.5-beta.9] - 2026-04-21
+
+### Added
+- Mobile ID verification support (VNT-1409, VNT-1419, VNT-1429, VNT-1455)
+  - Added `startMobileVerification()` function to initiate mobile verification sessions
+  - Added `createVerificationSession()` API function to create verification sessions with user ID and client ID
+  - Added WebSocket client (`WebSocketClient.js`) for real-time verification updates from AWS API Gateway
+  - Added mobile verification server address configuration with environment detection
+  - QR code generation for mobile verification sessions with customizable base URLs
+  - Real-time verification callbacks: `onVerificationStarted`, `onResult`, `onStatusChange`, `onError`
+  - Session management with session ID, session URL, WebSocket URL, and QR code SVG
+  - Connection state management (CONNECTING, OPEN, CLOSED, ERROR) for WebSocket connections
+
+### Changed
+- Updated environment detection to support mobile verification endpoints
+  - Mobile verification uses `staging.mdl.verantid.bluerocket.us` for staging
+  - Mobile verification uses `mdl.verantid.bluerocket.us` for production
+- Updated scanner type detection to use `scannerProfile` from scanner response in auto-DMV verification
+- Enhanced TypeScript definitions (`index.d.ts`) to include mobile verification types and callbacks
+
+## [1.4.5-beta.8] - 2026-04-15
+
+### Changed
+- Moved UV/IR image type definitions to scanner profile configuration
+  - Added `frontUvImageType`, `backUvImageType`, `frontIrImageType`, and `backIrImageType` to IDXpressPlus profile
+  - Updated image extraction logic to use profile-defined UV/IR types instead of hardcoded strings
+- Updated TypeScript definitions (`index.d.ts`) to include UV/IR base64 fields in `scanId` return type
+- Removed UV/IR fields from local scanner functions (`localScanId`, `localContinueScanId`) as local scanners do not support UV/IR imaging
+
+### Fixed
+- Eliminated redundant variable declarations in `ScannerApi.js` by declaring UV/IR variables at function scope
+
+## [1.4.5-beta.7] - 2026-04-15
+
+### Changed
+- Internal refactoring and code review fixes
+
+## [1.4.5-beta.6] - 2026-04-15
+
+### Added
+- UV/IR image support for IDXpressPlus scanner profile
+  - Added `licenseFrontUvBase64`, `licenseBackUvBase64`, `licenseFrontIrBase64`, and `licenseBackIrBase64` fields to scan results
+  - Scanner now captures and returns ultraviolet (UV) and infrared (IR) images alongside standard color images
+  - Image types supported: fclr (front color), rclr (rear color), fclruv (front UV), rclruv (rear UV), fgsir (front IR), rgsir (rear IR)
+
+### Fixed
+- Image extraction logic now captures all image types from scanner response instead of only front/back color images
+
+### Changed
+- Updated IDXpressPlus scanner profile to include UV/IR parameters in default settings and restore configuration
+  - Added `clrUvIrResolution`, `fclrUvEnabled`, `rclrUvEnabled`, `fgsIrEnabled`, and `rgsIrEnabled` to `restoreParamKeys`
+- Updated `ScannerApi.js` to extract UV/IR images from GetDocument response
+- Updated `CloudScan.js` `scanId` function to return UV/IR image data (`licenseFrontUvBase64`, `licenseBackUvBase64`, `licenseFrontIrBase64`, `licenseBackIrBase64`)
+- Local scanner functions (`localScanId`, `localContinueScanId`) do not include UV/IR fields as local scanners (VerantId6S) do not support UV/IR imaging
+
+## [1.4.5-beta.5] - 2026-04-14
+
+### Changed
+- Applied dynamic environment URLs to face comparison feature
+
+## [1.4.5-beta.4] - 2026-04-14
+
+### Added
+- Error validation for invalid environment type
+
+### Changed
+- Updated default server URLs to production endpoints
+
+## [1.4.5-beta.3] - 2026-04-13
+
+### Fixed
+- Various bug fixes and code quality improvements
+
+## [1.4.5-beta.2] - 2026-04-12
+
+### Added
+- Dynamic environment detection for server URLs
+- Support for multiple deployment environments
+
+### Changed
+- Server address handling now supports trailing slashes
+- Code improvements based on Copilot suggestions
+
+## [1.4.5-beta.1] - 2026-04-11
+
+### Added
+- IDXpress scanner profiles support
+- New scanner profile configuration options
+
+---
+
+## Version Number Guide
+
+- **Major** (1.x.x): Breaking changes
+- **Minor** (x.4.x): New features, backwards compatible
+- **Patch** (x.x.5): Bug fixes, backwards compatible
+- **Beta** (x.x.x-beta.x): Pre-release versions for testing