@myazahq/kyc-sdk-react-native 2.0.2 → 2.1.0

package/src/services/contactErrors.ts

@@ -0,0 +1,43 @@
+import { KYCApiError } from './api';
+
+// ---------------------------------------------------------------------------
+// User-facing copy for the contact-verification send/check failures.
+//
+// Each message says what happened AND what to do next, because every one of
+// these is recoverable and the user is mid-flow. A bare "something went wrong"
+// on an expired code leaves them retyping the same dead digits.
+// ---------------------------------------------------------------------------
+
+const CHECK_ERRORS: Record<string, string> = {
+  invalid_code: 'That code is not correct. Please try again.',
+  challenge_expired: 'This code has expired. Request a new one.',
+  too_many_attempts: 'Too many incorrect attempts. Request a new code.',
+  challenge_not_found: 'This code is no longer valid. Request a new one.',
+};
+
+const SEND_ERRORS: Record<string, string> = {
+  invalid_destination: 'That does not look valid. Please check and try again.',
+  send_rate_limited: 'Too many codes requested. Please wait a while and try again.',
+  send_failed: 'We could not send the code. Please try again.',
+};
+
+function describe(err: unknown, map: Record<string, string>): string {
+  if (err instanceof KYCApiError && err.code && map[err.code]) return map[err.code]!;
+  if (err instanceof TypeError) return 'Network error. Check your connection and try again.';
+  return 'Something went wrong. Please try again.';
+}
+
+export const describeSendError = (err: unknown): string => describe(err, SEND_ERRORS);
+export const describeCheckError = (err: unknown): string => describe(err, CHECK_ERRORS);
+
+/**
+ * Attempts left after a wrong code, when the server reports it.
+ *
+ * Showing the count is what stops a user burning the whole budget guessing —
+ * absent it they have no signal that the code is about to die.
+ */
+export function attemptsRemaining(err: unknown): number | undefined {
+  if (!(err instanceof KYCApiError)) return undefined;
+  const value = err.body?.attemptsRemaining;
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}

package/src/services/deviceMetadata.ts

@@ -14,7 +14,7 @@ export type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
  * Single source of truth for the SDK version — also used by `services/api.ts`
  * for the `X-SDK-Version` header. Keep in sync with `package.json`.
  */
-export const SDK_VERSION = '2.0.2';
+export const SDK_VERSION = '2.1.0';
 
 export interface ReactNativeDeviceMetadata {
   sdkType: 'react-native';

package/src/services/documentPicker.ts

@@ -0,0 +1,20 @@
+/**
+ * `expo-document-picker`, loaded on demand.
+ *
+ * A static import runs the module's native lookup at MODULE load, which throws
+ * `Cannot find native module 'ExpoDocumentPicker'` on any host app that has not
+ * rebuilt to pick it up — taking down the whole SDK, including flows that never
+ * choose a file. Requiring it at the moment the user taps means the capability
+ * degrades to photo-only where it is unavailable, matching the null-degrade
+ * posture the platform uses for every other optional native dependency.
+ */
+export type DocumentPickerModule = typeof import('expo-document-picker');
+
+export function loadDocumentPicker(): DocumentPickerModule | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require('expo-document-picker') as DocumentPickerModule;
+  } catch {
+    return null;
+  }
+}

package/src/services/fingerprint-sources.ts

@@ -0,0 +1,129 @@
+import { OS } from '../utils/platform';
+
+import type { FingerprintComponents } from './fingerprint';
+
+// ---------------------------------------------------------------------------
+// Where each fingerprint component comes from.
+//
+// Split from fingerprint.ts (200-line rule). Every accessor is guarded: a host
+// app missing one of these Expo modules must lose that ONE signal, not the
+// whole fingerprint and certainly not the submission.
+// ---------------------------------------------------------------------------
+
+/**
+ * Runs a literal `require(...)`, returning undefined if it throws.
+ *
+ * Metro needs a STRING LITERAL module name, so each caller passes its own
+ * loader. Under the Node test runner the native modules do not resolve and the
+ * loader throws — caught here, which is what lets these tests run at all.
+ */
+export function tryRequire<T>(loader: () => T): T | undefined {
+  try {
+    return loader();
+  } catch {
+    return undefined;
+  }
+}
+
+interface ExpoDeviceModule {
+  brand?: string | null;
+  manufacturer?: string | null;
+  modelName?: string | null;
+  isDevice?: boolean;
+  osVersion?: string | null;
+  osBuildId?: string | null;
+  totalMemory?: number | null;
+  supportedCpuArchitectures?: string[] | null;
+}
+
+interface ExpoApplicationModule {
+  getIosIdForVendorAsync?: () => Promise<string | null>;
+  getAndroidId?: () => string | null;
+}
+
+interface ExpoLocalizationModule {
+  getLocales?: () => Array<{ languageTag?: string }>;
+}
+
+/**
+ * React Native's own APIs, behind the same guarded require the rest of the SDK's
+ * pure modules use (see utils/platform.ts).
+ *
+ * A static `import … from 'react-native'` here would pull the whole RN module
+ * graph into the STORE's import chain, which the plain-Node test runner cannot
+ * parse — taking the flow-navigation tests down with it. This is the only
+ * reason the fingerprint reaches RN indirectly.
+ */
+interface ReactNativeApis {
+  Dimensions?: { get: (dim: string) => { width: number; height: number } };
+  PixelRatio?: { get: () => number; getFontScale: () => number };
+  Platform?: { Version?: string | number };
+}
+
+export function reactNative(): ReactNativeApis | undefined {
+  return tryRequire<ReactNativeApis>(() => require('react-native'));
+}
+
+/** `Platform.Version` is a string on iOS and a number (API level) on Android. */
+export function platformVersion(): string | undefined {
+  const version = reactNative()?.Platform?.Version;
+  if (version === undefined || version === null) return undefined;
+  const text = String(version);
+  return text === '' ? undefined : text;
+}
+
+export function safeTimezone(): string | undefined {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+    return undefined;
+  }
+}
+
+export function safeLanguages(): string[] | undefined {
+  const localization = tryRequire<ExpoLocalizationModule>(() => require('expo-localization'));
+  try {
+    const tags = localization?.getLocales?.()
+      .map((l) => l.languageTag)
+      .filter((tag): tag is string => typeof tag === 'string' && tag !== '');
+    return tags && tags.length > 0 ? tags : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function safeScreen(): FingerprintComponents['screen'] {
+  try {
+    const rn = reactNative();
+    if (!rn?.Dimensions || !rn.PixelRatio) return undefined;
+    const { width, height } = rn.Dimensions.get('screen');
+    // Rounded because RN reports fractional logical pixels on some devices, and
+    // a hash that changes with a rounding wobble is not an identifier.
+    return {
+      width: Math.round(width),
+      height: Math.round(height),
+      scale: rn.PixelRatio.get(),
+      fontScale: rn.PixelRatio.getFontScale(),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** The OS-vended per-install id. Async because iOS's is. */
+export async function persistentDeviceId(): Promise<string | undefined> {
+  const application = tryRequire<ExpoApplicationModule>(() => require('expo-application'));
+  if (!application) return undefined;
+  try {
+    if (OS === 'ios') return (await application.getIosIdForVendorAsync?.()) ?? undefined;
+    if (OS === 'android') return application.getAndroidId?.() ?? undefined;
+  } catch {
+    /* the OS declined — the fingerprint still works without it */
+  }
+  return undefined;
+}
+
+/** expo-device, or undefined when it is not installed. */
+export function expoDevice(): ExpoDeviceModule | undefined {
+  return tryRequire<ExpoDeviceModule>(() => require('expo-device'));
+}

package/src/services/fingerprint.ts

@@ -0,0 +1,101 @@
+import { OS } from '../utils/platform';
+import {
+  persistentDeviceId,
+  safeLanguages,
+  safeScreen,
+  safeTimezone,
+  platformVersion,
+  expoDevice,
+} from './fingerprint-sources';
+
+// ---------------------------------------------------------------------------
+// Device Intelligence — the client fingerprint.
+//
+// The SDK sends RAW components and never a self-computed id: the server
+// canonicalises and hashes them, so a client cannot mint a fresh identity by
+// posting a random hash. Everything is best-effort — a component that cannot be
+// read is simply omitted, and the server scores what it gets.
+//
+// The components differ from the web SDK's on purpose. There is no WebGL
+// renderer or canvas to hash here, but a native app can answer questions a
+// browser cannot: whether it is running on real hardware rather than an
+// emulator, and a per-install identifier the OS itself vends. Those are
+// stronger signals than anything the browser fingerprint recovers.
+//
+// `deviceHash` is a RISK SIGNAL, never an identity link — phone models collide
+// constantly, and merging two people because they own the same handset would
+// corrupt the identity graph.
+// ---------------------------------------------------------------------------
+
+export interface FingerprintComponents {
+  screen?: { width: number; height: number; scale: number; fontScale: number };
+  timezone?: string;
+  languages?: string[];
+  platform?: string;
+  osVersion?: string;
+  /** Device maker + model, as the OS reports them. */
+  brand?: string;
+  manufacturer?: string;
+  model?: string;
+  /** Total RAM in bytes — the native counterpart of the web's deviceMemory. */
+  totalMemory?: number;
+  cpuArchitectures?: string[];
+  /** OS build identifier — differs between a stock ROM and a modified one. */
+  osBuildId?: string;
+  /**
+   * FALSE means an emulator or simulator. The single most useful signal here:
+   * a real user is not verifying their identity from an Android emulator, and
+   * unlike the web's headless heuristics this is a direct answer from the OS.
+   */
+  isPhysicalDevice?: boolean;
+  /** True when the app is running from a development client / debug build. */
+  isDevelopmentBuild?: boolean;
+}
+
+export interface ClientFingerprint {
+  /**
+   * Per-install identifier vended by the OS — `identifierForVendor` on iOS,
+   * `ANDROID_ID` on Android. Preferred over a self-generated UUID in storage:
+   * it survives app data being cleared on iOS, needs no storage dependency, and
+   * cannot be spoofed from JavaScript. Resets on uninstall, which is correct —
+   * it identifies an install, not a person.
+   */
+  deviceId?: string;
+  components: FingerprintComponents;
+}
+
+/**
+ * Collect the fingerprint.
+ *
+ * Async only because iOS's vendor id is; everything else is synchronous. It is
+ * called once at submit and must never throw — a fingerprint that fails to
+ * collect is a missing signal, not a failed verification.
+ */
+export async function collectFingerprint(): Promise<ClientFingerprint> {
+  const device = expoDevice();
+
+  const components: FingerprintComponents = {
+    screen: safeScreen(),
+    timezone: safeTimezone(),
+    languages: safeLanguages(),
+    platform: OS,
+    osVersion: device?.osVersion ?? platformVersion(),
+    brand: device?.brand ?? undefined,
+    manufacturer: device?.manufacturer ?? undefined,
+    model: device?.modelName ?? undefined,
+    totalMemory: device?.totalMemory ?? undefined,
+    cpuArchitectures: device?.supportedCpuArchitectures ?? undefined,
+    osBuildId: device?.osBuildId ?? undefined,
+    isPhysicalDevice: device?.isDevice,
+    isDevelopmentBuild: typeof __DEV__ === 'boolean' ? __DEV__ : undefined,
+  };
+
+  return {
+    deviceId: await persistentDeviceId(),
+    // Undefined entries are stripped so the server canonicalises the same shape
+    // whether a module was missing or a value was genuinely absent.
+    components: Object.fromEntries(
+      Object.entries(components).filter(([, v]) => v !== undefined),
+    ) as FingerprintComponents,
+  };
+}

package/src/services/haptics.ts

@@ -0,0 +1,38 @@
+import { Vibration } from 'react-native';
+
+/**
+ * A success buzz, best-effort.
+ *
+ * A chip read has no shutter, no sound and nothing physical — the haptic is
+ * what makes it land as a completed action rather than a screen that quietly
+ * changed.
+ *
+ * `expo-haptics` gives the proper taptic pattern, but it is NOT a dependency of
+ * this SDK: adding one for a single buzz would force every consumer to rebuild.
+ * So it is loaded on demand where the host app already has it, and otherwise
+ * this falls back to RN's built-in vibrate, which needs nothing. Hardware with
+ * no taptic engine does nothing at all, which is also fine.
+ */
+export function successHaptic(): void {
+  try {
+    // Typed structurally rather than via `typeof import(...)`: the package is
+    // not a dependency here, so a type import would fail to resolve and break
+    // the build for the sake of a buzz.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const haptics = require('expo-haptics') as {
+      notificationAsync: (t: unknown) => Promise<void>;
+      NotificationFeedbackType: { Success: unknown };
+    };
+    void haptics
+      .notificationAsync(haptics.NotificationFeedbackType.Success)
+      .catch(() => undefined);
+    return;
+  } catch {
+    // Not installed — fall through to the built-in.
+  }
+  try {
+    Vibration.vibrate(30);
+  } catch {
+    // A device that refuses to vibrate is not a problem worth reporting.
+  }
+}

package/src/services/mediaCompress.ts

@@ -79,9 +79,14 @@ export async function cropImage(uri: string, rect: CropRect): Promise<string> {
  * CameraViewfinder shows the preview `BoxFit.cover` in a fixed 3:4 box with the
  * guide centred at 88% width and `aspect` height (mirrors the SVG overlay).
  */
-export async function cropCardRegion(uri: string, aspect: number): Promise<string> {
+export async function cropCardRegion(
+  uri: string,
+  aspect: number,
+  /** Aspect of the box the preview actually rendered in (width ÷ height). */
+  viewAr?: number,
+): Promise<string> {
   const { width, height } = await imageSize(uri);
-  return cropImage(uri, cardCropRect(width, height, aspect));
+  return cropImage(uri, cardCropRect(width, height, aspect, viewAr));
 }
 
 /** Compress a document still for OCR. Returns a new file URI. */

package/src/services/resolveUrl.ts

@@ -20,8 +20,8 @@ export type SdkEnvironment = 'development' | 'sandbox' | 'production';
 /** Canonical base URLs for the non-development environments. */
 const BASE_URLS: Record<Exclude<SdkEnvironment, 'development'>, string> = {
   // Sandbox and production share the same host; the key prefix selects the env.
-  sandbox: 'https://identity.myaza.app',
-  production: 'https://identity.myaza.app',
+  sandbox: 'https://trust.myaza.app',
+  production: 'https://trust.myaza.app',
 };
 
 /**

package/src/services/workflowGate.ts

@@ -0,0 +1,138 @@
+import { createKYCApi } from './api';
+import { KYCApiError } from './api';
+import { resolveBaseUrl } from './resolveUrl';
+import { mergeWorkflowConfig, overlayApplicantWorkflow } from '../config/workflowMerge';
+import { KYCError } from '../types/verification';
+import type { MyazaKYCConfig, ResolvedKYCConfig } from '../types/config';
+import type { ServerConfigState } from '../store/serverConfig';
+
+// ---------------------------------------------------------------------------
+// Resolve-before-mount.
+//
+// A config carrying a `workflowId` needs the published flow BEFORE anything
+// renders: the flow supplies `country`, the step toggles and the appearance, so
+// mounting first would show the wrong flow and then rearrange it under the user.
+// One round trip also returns the org's ID-type allowlist and branding, so the
+// separate `/config` call is skipped entirely.
+//
+// Two things the Flutter SDK's gate does NOT have and this one must:
+//
+//   • a TIMEOUT — its barrier is `barrierDismissible: false` with no deadline,
+//     so a request that never settles (a captive-portal Wi-Fi, a dead VPN) hangs
+//     the user on a spinner with no way out;
+//   • CANCELLATION — closing the sheet mid-resolve leaves the request in flight
+//     and its completion handler pointed at a screen that is gone.
+//
+// Both live here rather than in the component, so a caller cannot forget them.
+// ---------------------------------------------------------------------------
+
+/** How long to wait for a workflow before giving up. */
+export const WORKFLOW_RESOLVE_TIMEOUT_MS = 15_000;
+
+export interface WorkflowGateResult {
+  config: ResolvedKYCConfig;
+  /** Preloaded server config, so the flow skips its own `/config` fetch. */
+  serverConfig: ServerConfigState;
+}
+
+/** Distinguishes "we gave up waiting" from "the server said no". */
+export class WorkflowTimeoutError extends Error {
+  constructor() {
+    super('Timed out loading the verification workflow.');
+    this.name = 'WorkflowTimeoutError';
+    Object.setPrototypeOf(this, WorkflowTimeoutError.prototype);
+  }
+}
+
+function toKycError(err: unknown): KYCError {
+  if (err instanceof WorkflowTimeoutError) {
+    return new KYCError(
+      'network_error',
+      'We could not reach the verification service. Check your connection and try again.',
+    );
+  }
+  if (err instanceof KYCApiError) {
+    return new KYCError(
+      err.statusCode === 401 ? 'invalid_api_key' : 'invalid_workflow',
+      err.statusCode === 401
+        ? 'Invalid API key. Please contact support.'
+        : 'This verification workflow could not be loaded. Please contact support.',
+    );
+  }
+  return new KYCError('invalid_workflow', 'This verification workflow could not be loaded.');
+}
+
+/**
+ * Resolve the workflow and merge it over the props.
+ *
+ * `signal` aborts the request — pass the caller's so an abandoned resolve stops
+ * consuming the network rather than merely being ignored. Rejects with a
+ * {@link KYCError}; the timeout surfaces as `network_error` because that is what
+ * it is from the user's side.
+ */
+export async function resolveWorkflow(
+  config: MyazaKYCConfig,
+  signal?: AbortSignal,
+): Promise<WorkflowGateResult> {
+  const api = createKYCApi(resolveBaseUrl(config.apiKey, config.devUrl), config.apiKey);
+
+  // The deadline is ours, not the platform's: React Native's fetch has no
+  // default request timeout, so without this a socket that is open but silent
+  // never settles.
+  const controller = new AbortController();
+  const abort = (): void => controller.abort();
+  signal?.addEventListener('abort', abort);
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, WORKFLOW_RESOLVE_TIMEOUT_MS);
+
+  try {
+    const res = await api.workflow(config.workflowId!, controller.signal);
+    return {
+      // KYB: the mapped applicant workflow's capture template overlays the
+      // merged config (and its id is recorded for stamping) — see
+      // overlayApplicantWorkflow.
+      config: overlayApplicantWorkflow(
+        res.applicantWorkflow,
+        mergeWorkflowConfig(res.config, config as unknown as Record<string, unknown>),
+      ) as unknown as ResolvedKYCConfig,
+      serverConfig: {
+        status: 'ready',
+        idTypes: res.idTypes,
+        branding: res.branding,
+        environment: res.environment,
+        fatal: false,
+      },
+    };
+  } catch (err) {
+    // An abort we caused by the deadline reads as a timeout; an abort the
+    // caller caused is a cancellation and must propagate untranslated, so the
+    // caller can tell "the user left" from "this failed".
+    if (timedOut) throw toKycError(new WorkflowTimeoutError());
+    if (signal?.aborted) throw err;
+    throw toKycError(err);
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', abort);
+  }
+}
+
+/**
+ * The config to mount with when there is no workflow to resolve.
+ *
+ * Without a `workflowId` the consumer must supply `country` themselves — the
+ * flow cannot pick ID types, guides or endpoints without one. Failing here with
+ * a named error beats the alternative, which is a flow that mounts and then
+ * shows an empty ID-type list.
+ */
+export function requireCountry(config: MyazaKYCConfig): ResolvedKYCConfig {
+  if (!config.country) {
+    throw new KYCError(
+      'invalid_config',
+      'A `country` is required unless you pass a `workflowId`.',
+    );
+  }
+  return config as ResolvedKYCConfig;
+}

package/src/specs/MyazaEmrtd.nitro.ts

@@ -0,0 +1,114 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+
+// ---------------------------------------------------------------------------
+// Nitro spec for eMRTD chip reading: the NFC transport, plus the crypto
+// primitives the protocol is built from.
+//
+// WHY THE CRYPTO IS NATIVE. The protocol logic — APDU construction, TLV
+// parsing, secure messaging, key derivation, passive authentication — lives in
+// TypeScript, where it is testable against ICAO 9303's own worked examples
+// without a passport in hand. But the PRIMITIVES (3DES, AES, SHA, CMAC) come
+// from the platform: CommonCrypto on iOS, javax.crypto on Android. Both are
+// audited, constant-time where it matters, and hardware-accelerated. A
+// hand-written DES in JavaScript would be slower and, far worse, a novel
+// implementation on a path that authenticates a passport.
+//
+// Everything crosses the bridge as base64, because Nitro has no byte-array
+// type and hex would double the payload of a 256KB DG2.
+// ---------------------------------------------------------------------------
+
+/** How the chip was unlocked. */
+export type EmrtdAccessMethod = 'bac' | 'pace' | 'none';
+
+export interface EmrtdTagInfo {
+  /** True once a chip is in range and an ISO-DEP channel is open. */
+  connected: boolean;
+  /** Card UID, base64. Diagnostic only — never an identity signal. */
+  uid: string;
+}
+
+export interface EmrtdApduResponse {
+  /** Response data (no status word), base64. */
+  data: string;
+  /** SW1<<8 | SW2. 0x9000 is success; 0x63CF and 0x6Cxx are meaningful too. */
+  statusWord: number;
+}
+
+export interface MyazaEmrtd extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  /** Whether this device has NFC hardware capable of ISO-DEP. */
+  isAvailable(): boolean;
+
+  /**
+   * Begin a session and wait for a chip.
+   *
+   * `alertMessage` is shown in iOS's system NFC sheet; Android has no
+   * equivalent and ignores it.
+   */
+  startSession(alertMessage: string): Promise<EmrtdTagInfo>;
+
+  /** End the session. Safe to call when none is open. */
+  stopSession(message: string): Promise<void>;
+
+  /**
+   * Update the live session's user-facing message.
+   *
+   * iOS narrates the read on its system sheet — which covers the app, so this
+   * is the ONLY feedback an iOS user gets between "hold your phone here" and
+   * the result. Android has no system NFC UI and ignores it (the SDK's own
+   * screen narrates there). Safe to call when no session is open.
+   */
+  updateSessionMessage(message: string): Promise<void>;
+
+  /**
+   * Send one APDU and return the response.
+   *
+   * A transport error rejects; a chip that answers with a non-success status
+   * word RESOLVES with that word, because those are protocol answers the
+   * caller must interpret rather than failures.
+   */
+  transceive(apduBase64: string): Promise<EmrtdApduResponse>;
+
+  /**
+   * Decode an image the JS side cannot render, returning JPEG bytes.
+   *
+   * The one that matters is JPEG 2000: most passport chips store their portrait
+   * (DG2) that way and React Native has no decoder for it, so the photo the
+   * issuing government put on the chip could be read and verified but never
+   * shown. The platform does have one — iOS registers `public.jpeg-2000` with
+   * ImageIO, Android with BitmapFactory.
+   *
+   * Returns an EMPTY STRING rather than null when the format is not understood
+   * — Nitro maps a nullable string to a variant type, which costs both native
+   * sides an unwrapping dance for a value whose only meaning is "no picture".
+   * Never throws: the portrait is a courtesy preview and the chip read stands on
+   * its own without it.
+   */
+  decodeImage(dataBase64: string): Promise<string>;
+
+  // ── Crypto primitives ─────────────────────────────────────────────────────
+
+  /** SHA-1 digest, base64 in and out. */
+  sha1(dataBase64: string): string;
+  /** SHA-256 digest. */
+  sha256(dataBase64: string): string;
+
+  /**
+   * Two-key 3DES (K1|K2|K1) in CBC mode.
+   *
+   * `ivBase64` is empty for the zero IV that BAC uses. No padding is applied —
+   * ISO 9797-1 method 2 padding is the protocol's job, not the cipher's.
+   */
+  desEde2Cbc(keyBase64: string, dataBase64: string, ivBase64: string, encrypt: boolean): string;
+
+  /** Single DES on ONE block — the retail MAC's inner primitive. */
+  desBlock(keyBase64: string, blockBase64: string, encrypt: boolean): string;
+
+  /** AES-CBC, for the AES cipher suites PACE may negotiate. */
+  aesCbc(keyBase64: string, dataBase64: string, ivBase64: string, encrypt: boolean): string;
+
+  /** AES-CMAC (RFC 4493), truncated by the caller as ICAO specifies. */
+  aesCmac(keyBase64: string, dataBase64: string): string;
+
+  /** Cryptographically secure random bytes — the BAC challenge depends on it. */
+  randomBytes(length: number): string;
+}

package/src/specs/MyazaFaceDetector.nitro.ts

@@ -32,6 +32,16 @@ export interface FaceResult {
   faceSizeRatio: number; // face width / frame width (0–1)
   faceCount: number; // # faces in frame; 0 = no face
   brightness: number; // mean luma of the frame (0–255), for the low-light gate
+  faceCenterX: number; // face centre X, normalised 0–1 (−1 when unavailable)
+  faceCenterY: number; // face centre Y, normalised 0–1 (−1 when unavailable)
+  trackingId: number; // ML Kit per-face id; −1 on iOS / when untracked
+  // Mean RGB of the FACE REGION (0–255 each), for flash (screen-reflection)
+  // liveness. Sampled in this same pass because the pixel buffer is already
+  // mapped here — a second native module would mean a second frame walk for
+  // numbers we can take for free. −1 when no face was found.
+  faceR: number;
+  faceG: number;
+  faceB: number;
 }
 
 export interface MyazaFaceDetector extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {