verant_id_cloud_scan 1.4.5-beta.9 → 1.4.6-beta.0

package/.github/workflows/publish_library.yml

@@ -24,4 +24,12 @@ jobs:
         run: npm install -g npm@latest
         
       - name: Publish to npm
-        run: npm publish
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          if [[ "$VERSION" == *-* ]]; then
+            echo "Publishing prerelease $VERSION under the 'beta' dist-tag"
+            npm publish --tag beta
+          else
+            echo "Publishing release $VERSION under 'latest'"
+            npm publish
+          fi

package/Api.js

@@ -264,9 +264,60 @@ export const checkFaceComparisonFeatureLicense = async (clientId) => {
   }
 }
 
-export const checkLicense = async (clientId, macAddress) => {
+export const checkDigitalIDFeatureLicense = async (clientId) => {
+  const url = getLicenseServerAddress() + "/mobile_id/check_license";
+  const data = { client_id: clientId };
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(data),
+    });
+
+    // Extract the JSON data from the response
+    const responseData = await response.json();
+
+    if (response.ok && responseData.licensed === true) {
+      return true; // Successful response
+    } else {
+      console.log(
+        "checkDigitalIDFeatureLicense returned false or non 200:",
+        responseData
+      );
+      return false; // Unsuccessful response
+    }
+  } catch (error) {
+    console.error(
+      "There was a problem with the checkDigitalIDFeatureLicense request:",
+      error
+    );
+    return false; // Error occurred
+  }
+};
+
+// 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, mac_address: macAddress };
+  const data = { client_id: clientId };
+  if (macAddress) data.mac_address = macAddress;
+  if (serialNumber) data.serial_number = serialNumber;
 
   try {
     const response = await fetch(url, {
@@ -346,48 +397,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}`;
-  }
-
-  // Remove trailing slash to prevent double slashes in URL
-  formattedAddress = formattedAddress.replace(/\/+$/, '');
-
-  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) =>
@@ -414,42 +565,174 @@ 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,
+  };
+};
+
+/**
+ * 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",
+  };
 
-    const connectResponse = await postToScannerApi(scannerAddress, connectCommand, 5000);
+  const probe = await postToScannerApiDetailed(
+    scannerAddress,
+    connectCommand,
+    5000,
+    signal,
+  );
 
-    // If connection failed or no session ID, scanner not present
-    if (!connectResponse || !connectResponse.SessionId) {
-      return false;
-    }
+  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,
+      },
+    };
+  }
 
-    // Successfully connected and disconnected
-    return true;
-  } catch (error) {
-    // Any error means scanner is not reachable
-    return false;
+  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;
 };
 
 /**
@@ -460,11 +743,16 @@ export const checkScannerPresent = async (scannerAddress) => {
  *
  * @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) => {
+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, {
@@ -479,24 +767,31 @@ export const createVerificationSession = async (userId, clientId) => {
       const responseData = await response.json();
       return responseData;
     } else {
-      // Try to parse error response
+      // 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 {
-        const errorData = await response.json();
+        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
-        };
-      } catch (parseError) {
-        const errorText = await response.text();
-        console.error("Verification session creation failed:", errorText);
-        return {
-          status: 'error',
-          message: 'Failed to create verification session',
-          raw_error: errorText
+          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);