@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/transport/api.ts

@@ -0,0 +1,257 @@
+/**
+ * @fileoverview Secure, centralized API caller for the Velion Onboarding SDK.
+ *
+ * The SDK version comes from `utils/sdkVersion.ts` (a regular module constant)
+ * instead of bundler-injected globals so this code runs identically in Metro.
+ *
+ * Design decisions:
+ * - **Factory pattern** (`createApiCaller`): Returns a pre-configured caller
+ *   bound to a specific `baseUrl` and `sessionToken`. Modules receive this
+ *   caller and never have direct access to the token string.
+ * - **No API keys**: Only the short-lived `sessionToken` (Bearer) is used.
+ * - **AbortController integration**: All calls accept an optional signal,
+ *   enabling clean cancellation when `VelionOnboarding.destroy()` is called.
+ * - **Structured errors**: All failures are normalized into `SdkError` objects
+ *   with machine-readable codes, never raw exceptions.
+ */
+
+import { SdkErrorCode, type SdkError } from '../types';
+import { isSecureHttpUrl } from './secureUrl';
+import { log } from '../utils/log';
+import { SDK_VERSION } from '../utils/sdkVersion';
+
+/** Hours of clock skew tolerated before we warn the user about an inaccurate device clock. */
+const CLOCK_SKEW_WARN_HOURS = 24;
+
+const SESSION_EXPIRED_CODE = SdkErrorCode.SESSION_EXPIRED;
+
+interface BackendErrorBody {
+  message?: string;
+  code?: string;
+  details?: unknown;
+}
+
+function buildApiError(
+  message: string,
+  httpStatus?: number,
+  cause?: unknown,
+): SdkError {
+  let code: SdkErrorCode;
+
+  if (httpStatus === 401) {
+    code = SdkErrorCode.SESSION_EXPIRED;
+  } else if (httpStatus === 403) {
+    code = SdkErrorCode.SESSION_INVALID;
+  } else if (httpStatus === undefined || httpStatus === 0) {
+    code = SdkErrorCode.NETWORK_ERROR;
+  } else {
+    code = SdkErrorCode.API_ERROR;
+  }
+
+  return {
+    code,
+    message,
+    cause,
+    ...(httpStatus !== undefined && { httpStatus }),
+  } satisfies SdkError;
+}
+
+export interface ApiCallOptions {
+  /** AbortSignal to cancel the in-flight request. */
+  signal?: AbortSignal;
+  /** Additional headers to merge on top of the default auth headers. */
+  extraHeaders?: Record<string, string>;
+}
+
+/**
+ * Creates a pre-authorized API caller bound to a specific session.
+ * All requests include Authorization: Bearer <sessionToken>.
+ */
+export function createApiCaller(
+  rawBaseUrl: string,
+  sessionToken: string,
+  expiresAt?: string,
+) {
+  if (!isSecureHttpUrl(rawBaseUrl)) {
+    throw {
+      code: SdkErrorCode.UNKNOWN,
+      message:
+        `Insecure apiUrl: "${rawBaseUrl}". The SDK refuses to send the session token over a non-TLS channel. ` +
+        'Use https://; http:// is accepted only for loopback (localhost / 127.0.0.1 / ::1).',
+    } satisfies SdkError;
+  }
+  // Strip a trailing slash so concatenation with endpoints (which always
+  // start with `/`) never produces a double slash. This is the same
+  // normalization `sse.ts` already does.
+  const baseUrl = rawBaseUrl.replace(/\/$/, '');
+
+  let currentToken = sessionToken;
+  let currentExpiresAt = expiresAt;
+  let clockSkewWarned = false;
+
+  function ensureTokenValid(): void {
+    if (!currentExpiresAt) return;
+    const expiry = new Date(currentExpiresAt).getTime();
+    if (Number.isNaN(expiry)) return;
+    const now = Date.now();
+    const skewMs = now - expiry;
+    if (
+      !clockSkewWarned &&
+      Math.abs(skewMs) > CLOCK_SKEW_WARN_HOURS * 60 * 60 * 1000
+    ) {
+      clockSkewWarned = true;
+      log.warn(
+        '[api] device clock appears to be off by more than',
+        CLOCK_SKEW_WARN_HOURS,
+        'h relative to the session expiresAt; falling back to server-side 401 detection.',
+      );
+      return;
+    }
+    if (now >= expiry) {
+      throw {
+        code: SESSION_EXPIRED_CODE,
+        message:
+          'Session token has expired. Obtain a new session from your backend.',
+      } satisfies SdkError;
+    }
+  }
+
+  function buildAuthHeaders(extra?: Record<string, string>): Record<string, string> {
+    return {
+      ...extra,
+      Authorization: `Bearer ${currentToken}`,
+      'X-Velion-SDK-Version': SDK_VERSION,
+    };
+  }
+
+  function setSessionToken(token: string, expiresAtIso?: string): void {
+    currentToken = token;
+    currentExpiresAt = expiresAtIso;
+    clockSkewWarned = false;
+  }
+
+  async function call<TResponse>(
+    endpoint: string,
+    init: RequestInit,
+    options: ApiCallOptions = {},
+  ): Promise<TResponse> {
+    ensureTokenValid();
+    const url = `${baseUrl}${endpoint}`;
+
+    let response: Response;
+    try {
+      const initWithSignal =
+        options.signal !== undefined
+          ? { ...init, signal: options.signal }
+          : init;
+      response = await fetch(url, initWithSignal);
+    } catch (networkErr) {
+      const name = (networkErr as { name?: string } | null)?.name;
+      if (name === 'AbortError') {
+        throw networkErr;
+      }
+      throw buildApiError(
+        `Network request failed for "${endpoint}". Check connectivity.`,
+        undefined,
+        networkErr,
+      );
+    }
+
+    if (!response.ok) {
+      let errorBody: BackendErrorBody = {};
+      try {
+        errorBody = (await response.json()) as BackendErrorBody;
+      } catch {
+        // Body may not be JSON (e.g., a 502 from a proxy). That's fine.
+      }
+
+      throw buildApiError(
+        errorBody.message ??
+          `Backend returned ${response.status} on ${endpoint}.`,
+        response.status,
+        errorBody,
+      );
+    }
+
+    if (
+      response.status === 204 ||
+      response.headers.get('content-length') === '0'
+    ) {
+      return {} as TResponse;
+    }
+
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!contentType.includes('application/json')) {
+      return {} as TResponse;
+    }
+
+    try {
+      return (await response.json()) as TResponse;
+    } catch (parseErr) {
+      throw buildApiError(
+        `Failed to parse JSON response from "${endpoint}".`,
+        response.status,
+        parseErr,
+      );
+    }
+  }
+
+  async function get<TResponse>(
+    endpoint: string,
+    options?: ApiCallOptions,
+  ): Promise<TResponse> {
+    return call<TResponse>(
+      endpoint,
+      {
+        method: 'GET',
+        headers: buildAuthHeaders(options?.extraHeaders),
+      },
+      options,
+    );
+  }
+
+  async function post<TResponse>(
+    endpoint: string,
+    body: unknown,
+    options?: ApiCallOptions,
+  ): Promise<TResponse> {
+    return call<TResponse>(
+      endpoint,
+      {
+        method: 'POST',
+        headers: buildAuthHeaders({
+          'Content-Type': 'application/json',
+          ...options?.extraHeaders,
+        }),
+        body: JSON.stringify(body),
+      },
+      options,
+    );
+  }
+
+  /**
+   * Authenticated POST with a `FormData` body. RN's `fetch` mirrors the
+   * standard contract: don't set `Content-Type` so the runtime injects the
+   * multipart boundary.
+   */
+  async function postFormData<TResponse>(
+    endpoint: string,
+    formData: FormData,
+    options?: ApiCallOptions,
+  ): Promise<TResponse> {
+    return call<TResponse>(
+      endpoint,
+      {
+        method: 'POST',
+        headers: buildAuthHeaders(options?.extraHeaders),
+        body: formData,
+      },
+      options,
+    );
+  }
+
+  return { get, post, postFormData, setSessionToken } as const;
+}
+
+/** The type of the object returned by `createApiCaller`. */
+export type ApiCaller = ReturnType<typeof createApiCaller>;

package/src/transport/irisWebSocket.ts

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview Typed wrapper around the WebSocket connection to the Iris
+ * orchestrator.
+ *
+ *   - Server messages are JSON (`{ type, ... }`). See `IrisServerMessage`.
+ *   - Client → server frames are either:
+ *       a) raw `ArrayBuffer` JPEGs (when no HMAC key was returned), or
+ *       b) JSON envelopes signed with HMAC-SHA256 (see `utils/hmac`).
+ *
+ * The WebSocket global on RN supports both string and binary payloads, so we
+ * don't need any extra polyfills. We do require the URL to be `wss://`
+ * (or `ws://localhost:*` for dev) — TLS is enforced.
+ */
+
+import { isSecureWebSocketUrl } from './secureUrl';
+import { log } from '../utils/log';
+
+export type IrisChallenge =
+  | 'FACE_FORWARD'
+  | 'TURN_LEFT'
+  | 'TURN_RIGHT'
+  | 'SMILE'
+  | 'BLINK'
+  | 'MOVE_CLOSER'
+  | 'MOVE_FARTHER';
+
+export interface IrisServerMessage {
+  type:
+    | 'SESSION_READY'
+    | 'CHALLENGE'
+    | 'CHALLENGE_PROGRESS'
+    | 'CHALLENGE_COMPLETE'
+    | 'WARNING'
+    | 'ERROR'
+    | 'SESSION_COMPLETE';
+  /** Iris challenge identifier (only on CHALLENGE / CHALLENGE_PROGRESS). */
+  challenge?: IrisChallenge | string;
+  /** 0..1 confidence on CHALLENGE_PROGRESS. */
+  confidence?: number;
+  /** Free-form server-supplied message (warnings, errors). */
+  message?: string;
+  /** Discriminator for WARNING (e.g. POSITIONING_REQUIRED, SPOOF_RISK_HIGH). */
+  code?: string;
+  /** Bumps as the user keeps missing positioning. */
+  consecutiveMisses?: number;
+  /** Final score map on SESSION_COMPLETE. */
+  signals?: Record<string, number>;
+  /** Zero-based position of this challenge in the session sequence (CHALLENGE only). */
+  sequenceIndex?: number;
+  /** Total number of challenges in the session sequence (CHALLENGE only). */
+  totalChallenges?: number;
+}
+
+export interface IrisOpenOptions {
+  websocketUrl: string;
+  connectionToken?: string | undefined;
+  /** `'es'` or `'en'` — anything else collapses to `'en'` (Iris default). */
+  locale: string;
+  onMessage: (msg: IrisServerMessage) => void;
+  /** Fired when the underlying WebSocket reports an error event. */
+  onError?: (event: Event) => void;
+  /** Fired when the WebSocket closes (either side). */
+  onClose?: (code: number, reason: string) => void;
+  /** Fired once after `onopen`. */
+  onOpen?: () => void;
+}
+
+export interface IrisConnection {
+  /** Send a binary JPEG frame. Returns `false` if the socket is not open. */
+  sendBinary: (bytes: ArrayBufferView | ArrayBuffer) => boolean;
+  /** Send a JSON envelope (already serialized). Returns `false` if not open. */
+  sendJson: (envelope: string) => boolean;
+  /** Close with a normal `1000` code (or a custom one). Idempotent. */
+  close: (code?: number, reason?: string) => void;
+  /** True when `OPEN`. */
+  isOpen: () => boolean;
+}
+
+const WS_OPEN = 1;
+
+/** Builds the final connect URL with `?token=...&lang=...` query params. */
+export function buildIrisUrl(
+  websocketUrl: string,
+  connectionToken: string | undefined,
+  locale: string,
+): string {
+  let url = websocketUrl;
+  if (connectionToken) {
+    const sep = url.includes('?') ? '&' : '?';
+    url = `${url}${sep}token=${encodeURIComponent(connectionToken)}`;
+  }
+  const normalizedLang = locale.toLowerCase().startsWith('es') ? 'es' : 'en';
+  const langSep = url.includes('?') ? '&' : '?';
+  url = `${url}${langSep}lang=${normalizedLang}`;
+  return url;
+}
+
+/**
+ * Open a WebSocket against the Iris orchestrator. The URL must already include
+ * the customer's `connection_token` if Iris enforced auth.
+ *
+ * `onClose` fires for both clean (`code === 1000`) and unclean closures —
+ * callers decide how to react (terminal warning vs. unexpected drop).
+ */
+export function openIrisWebSocket(opts: IrisOpenOptions): IrisConnection {
+  if (!isSecureWebSocketUrl(opts.websocketUrl)) {
+    throw new Error(
+      `Iris websocket_url must be wss:// (or ws://localhost in dev). Got: "${opts.websocketUrl}"`,
+    );
+  }
+  const url = buildIrisUrl(opts.websocketUrl, opts.connectionToken, opts.locale);
+
+  log.info('[IrisWS] opening', { url: opts.websocketUrl });
+
+  const ws = new WebSocket(url);
+  let closed = false;
+
+  ws.onopen = () => {
+    log.info('[IrisWS] open');
+    opts.onOpen?.();
+  };
+
+  ws.onmessage = (event: WebSocketMessageEvent) => {
+    if (typeof event.data !== 'string') return;
+    try {
+      const parsed = JSON.parse(event.data) as IrisServerMessage;
+      opts.onMessage(parsed);
+    } catch {
+      // Iris only sends JSON; ignore noise.
+    }
+  };
+
+  ws.onerror = (event) => {
+    log.warn('[IrisWS] error', event);
+    opts.onError?.(event as Event);
+  };
+
+  ws.onclose = (event) => {
+    log.info('[IrisWS] close', { code: event.code, reason: event.reason });
+    closed = true;
+    opts.onClose?.(event.code, event.reason ?? '');
+  };
+
+  return {
+    sendBinary: (data) => {
+      if (closed || ws.readyState !== WS_OPEN) return false;
+      try {
+        ws.send(data as ArrayBuffer);
+        return true;
+      } catch (err) {
+        log.warn('[IrisWS] sendBinary failed', err);
+        return false;
+      }
+    },
+    sendJson: (envelope) => {
+      if (closed || ws.readyState !== WS_OPEN) return false;
+      try {
+        ws.send(envelope);
+        return true;
+      } catch (err) {
+        log.warn('[IrisWS] sendJson failed', err);
+        return false;
+      }
+    },
+    close: (code = 1000, reason = '') => {
+      if (closed) return;
+      closed = true;
+      try {
+        ws.close(code, reason);
+      } catch {
+        /* ignore */
+      }
+    },
+    isOpen: () => !closed && ws.readyState === WS_OPEN,
+  };
+}
+
+/**
+ * Subset of WARNING `code`s that mean "Iris is about to close, escalate to
+ * the in-flow retry dialog instead of the generic close handler".
+ */
+export const TERMINAL_WARNING_CODES = new Set<string>([
+  'SPOOF_RISK_HIGH',
+  'SESSION_TERMINATED',
+  'BIOMETRIC_LOCK',
+]);

package/src/transport/secureUrl.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Transport-security guards for runtime URLs.
+ *
+ * The SDK exchanges bearer tokens, KYC documents and selfies. A misconfigured
+ * `apiUrl`, a tampered `liveness-init` response, or a backend that returns a
+ * `ws://` URL would all leak that data in cleartext. These helpers force every
+ * runtime endpoint to use TLS, with a single carve-out for loopback hosts so
+ * developers can still run the SDK against a local backend.
+ */
+
+function isLocalhostHost(host: string): boolean {
+  // `URL.hostname` returns `[::1]` (with brackets) for IPv6 loopback in some
+  // engines and `::1` in others — accept both. Strict loopback only: arbitrary
+  // `*.local` (Bonjour) or `*.svc.cluster.local` hostnames are NOT exempted —
+  // the SDK refuses to send the session token over plain HTTP outside of
+  // loopback even if the host is reachable on the local network.
+  return (
+    host === 'localhost' ||
+    host === '127.0.0.1' ||
+    host === '::1' ||
+    host === '[::1]'
+  );
+}
+
+/** True when the URL is `https://`, or `http://localhost`-style for dev. */
+export function isSecureHttpUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    if (u.protocol === 'https:') return true;
+    if (u.protocol === 'http:') return isLocalhostHost(u.hostname);
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/** True when the URL is `wss://`, or `ws://localhost`-style for dev. */
+export function isSecureWebSocketUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    if (u.protocol === 'wss:') return true;
+    if (u.protocol === 'ws:') return isLocalhostHost(u.hostname);
+    return false;
+  } catch {
+    return false;
+  }
+}