@myazahq/kyc-sdk-react-native 2.4.0 → 2.6.0

package/src/emrtd/read.ts

@@ -2,6 +2,7 @@ import { Platform } from 'react-native';
 
 import { nativeModule } from './native';
 import { readChip, type EmrtdReadResult, EmrtdSessionError } from './session';
+import type { AaChallenge } from './activeAuth';
 import {
   MAX_CHIP_ATTEMPTS,
   chipRetryDelayMs,
@@ -37,6 +38,12 @@ export interface ChipReadOptions {
   successMessage?: string;
   /** Read progress, so the UI can narrate an otherwise invisible operation. */
   onStage?: (stage: NfcReadStage) => void;
+  /**
+   * The Active-Authentication challenge issued by the SERVER (8 bytes). Absent
+   * ⇒ the anti-clone step is skipped and the read is exactly what it was
+   * before — the whole capability null-degrades rather than failing.
+   */
+  aaChallenge?: AaChallenge;
 }
 
 /**
@@ -151,7 +158,7 @@ export async function readPassportChip(
 
     try {
       onStage('waiting');
-      const result = await readChip(native, mrz, onStage);
+      const result = await readChip(native, mrz, onStage, options.aaChallenge);
       if (!result.sod && attempt < MAX_CHIP_ATTEMPTS && !abandoned()) {
         partial = result;
         devLog(attempt, 'security-file', new Error('EF.SOD missing — retrying for a complete read'));

package/src/emrtd/session.ts

@@ -1,6 +1,8 @@
 import { fromBase64, toBase64 } from './bytes';
 import { buildBacChallenge, completeBac } from './bac';
 import { primitivesFromNative, type EmrtdPrimitives, type MrzKeyFields } from './crypto';
+import { readExtraGroups, type ExtraGroupReads } from './extras';
+import { readActiveAuth, type AaChallenge, type ActiveAuthRead } from './activeAuth';
 import { EF, readFile, type Transceive } from './files';
 import { readOptionalFile } from './optionalRead';
 import { PaceError, PREFER_PACE, tryPace, type PaceOutcome } from './open';
@@ -45,6 +47,22 @@ export interface EmrtdReadResult {
   sod?: string;
   /** DG2 — the portrait. Best-effort; the largest file and the likeliest to drop. */
   dg2?: string;
+  /** DG7 — the displayed signature image. Best-effort, COM-gated (see extras.ts). */
+  dg7?: string;
+  /** DG11 — additional personal details. Best-effort; many issuers omit it. */
+  dg11?: string;
+  /** DG12 — additional document details. Best-effort; many issuers omit it. */
+  dg12?: string;
+  /** DG15 — the chip's Active-Authentication public key. Absent on the many
+   *  chips that support no AA at all. */
+  dg15?: string;
+  /** The chip's signature over the SERVER's challenge — the anti-clone proof.
+   *  Verified server-side only; a client that checked its own chip could be
+   *  patched to say yes. */
+  aaSignature?: string;
+  /** Which server-issued challenge that signature answers — echoed back so the
+   *  server can spend it. Not read off the chip; carried through with it. */
+  aaChallengeId?: string;
   /** How the chip was unlocked. Reported to the server on the submission. */
   chipAuth: 'bac' | 'pace';
   /**
@@ -141,6 +159,12 @@ export async function readChip(
    * enough that silence reads as failure and prompts them to lift the document.
    */
   onStage?: (stage: NfcReadStage) => void,
+  /**
+   * The Active-Authentication challenge the SERVER issued, if it could. Ours to
+   * carry, never ours to choose: a client-chosen nonce makes a captured
+   * signature replayable, which is exactly the clone AA exists to catch.
+   */
+  aaChallenge?: AaChallenge,
 ): Promise<EmrtdReadResult> {
   const p = primitivesFromNative(native);
 
@@ -178,9 +202,20 @@ export async function readChip(
   const sod = await readOptionalFile(sm, transceive, EF.SOD, 'EF.SOD');
 
   let dg2: Uint8Array | null = null;
+  let extras: ExtraGroupReads = { dg7: null, dg11: null, dg12: null };
+  let activeAuth: ActiveAuthRead = {};
   if (sod) {
     onStage?.('readingPhoto');
     dg2 = await readOptionalFile(sm, transceive, EF.DG2, 'DG2');
+    // The optional detail groups come LAST: by now everything that matters is
+    // banked, so a drop here costs only nice-to-have context. Gated on the SOD
+    // like DG2 — the server authenticates each group against it.
+    onStage?.('readingDetails');
+    extras = await readExtraGroups(sm, transceive);
+    // The anti-clone challenge LAST: it is the only step that asks the chip to
+    // compute rather than read, so it is the slowest per byte and the one worth
+    // losing if the document leaves contact.
+    activeAuth = await readActiveAuth(sm, transceive, aaChallenge);
   }
   onStage?.('done');
 
@@ -188,6 +223,12 @@ export async function readChip(
     dg1: toBase64(dg1),
     ...(sod ? { sod: toBase64(sod) } : {}),
     ...(dg2 ? { dg2: toBase64(dg2) } : {}),
+    ...(extras.dg7 ? { dg7: toBase64(extras.dg7) } : {}),
+    ...(extras.dg11 ? { dg11: toBase64(extras.dg11) } : {}),
+    ...(extras.dg12 ? { dg12: toBase64(extras.dg12) } : {}),
+    ...(activeAuth.dg15 ? { dg15: activeAuth.dg15 } : {}),
+    ...(activeAuth.signature ? { aaSignature: activeAuth.signature } : {}),
+    ...(activeAuth.signature && aaChallenge ? { aaChallengeId: aaChallenge.id } : {}),
     chipAuth: access.chipAuth,
     paceOutcome: access.outcome,
     ...(access.detail ? { paceDetail: access.detail } : {}),

package/src/emrtd/stages.ts

@@ -23,6 +23,8 @@ export type NfcReadStage =
   | 'readingSecurity'
   /** Reading DG2 — the chip's portrait. */
   | 'readingPhoto'
+  /** Reading the optional detail groups (DG7/DG11/DG12) — small and quick. */
+  | 'readingDetails'
   /** Everything that could be read has been. */
   | 'done';
 
@@ -33,6 +35,7 @@ export const NFC_STAGE_ORDER: NfcReadStage[] = [
   'readingData',
   'readingSecurity',
   'readingPhoto',
+  'readingDetails',
   'done',
 ];
 
@@ -49,6 +52,8 @@ export function nfcStageLabel(stage: NfcReadStage): string {
       return 'Reading security data';
     case 'readingPhoto':
       return 'Reading photo';
+    case 'readingDetails':
+      return 'Reading extra details';
     case 'done':
       return 'Chip read complete';
   }
@@ -73,6 +78,8 @@ export function nfcStageDetail(stage: NfcReadStage): string {
       return 'Downloading the chip’s digital signature. This is the largest part and takes the longest — keep holding.';
     case 'readingPhoto':
       return 'Copying the photo stored on the chip.';
+    case 'readingDetails':
+      return 'Copying the optional details stored on the chip. These are small and quick.';
     case 'done':
       return 'Everything was read successfully.';
   }
@@ -98,6 +105,8 @@ export function nfcSheetMessage(stage: NfcReadStage): string {
       return 'Verifying security data — keep holding…';
     case 'readingPhoto':
       return 'Reading your photo — keep holding…';
+    case 'readingDetails':
+      return 'Almost done — keep holding…';
     case 'done':
       return 'Chip read complete';
   }
@@ -116,6 +125,8 @@ export function nfcStageProgress(stage: NfcReadStage): number {
       return 0.6;
     case 'readingPhoto':
       return 0.85;
+    case 'readingDetails':
+      return 0.95;
     case 'done':
       return 1;
   }

package/src/index.ts

@@ -11,6 +11,16 @@
 export { MyazaKYC, useMyazaKYC } from './MyazaKYC';
 export type { MyazaKYCProps, UseMyazaKYCReturn } from './MyazaKYC';
 
+// Returning-user face re-authentication (the web SDK's MyazaBiometricAuth).
+export { MyazaBiometricAuth } from './MyazaBiometricAuth';
+export type { MyazaBiometricAuthProps } from './MyazaBiometricAuth';
+export type {
+  BiometricAuthRequest,
+  BiometricAuthResponse,
+  BiometricStatusResponse,
+  BiometricLivenessClaim,
+} from './services/api-types-biometric';
+
 // Public config + callback types
 export type {
   MyazaKYCConfig,
@@ -32,6 +42,7 @@ export type {
   PhoneVerificationConfig,
   ProofOfAddressConfig,
   PoaDocumentType,
+  AddressCollectionConfig,
   QuestionnaireConfig,
   QuestionnaireField,
   QuestionnaireFieldOption,
@@ -56,7 +67,8 @@ export type {
   WorkflowBusinessDocumentTypeConfig,
   WorkflowBusinessApplicantConfig,
 } from './types/business';
-export type { KYCSubmission, KYCErrorCode, KYCErrorDetails } from './types/verification';
+export type { KYCSubmission, KYCResult, KYCErrorCode, KYCErrorDetails } from './types/verification';
+export type { BiometricFlowConfig, BiometricCopy, BiometricCopyText } from './config/biometricOptions';
 export { KYCError } from './types/verification';
 
 // ID-type matrix + helpers
@@ -107,6 +119,47 @@ export {
 export { hasActiveQuestionnaire, questionnaireAnswerKeys } from './config/questionnaire';
 export { hasEmailVerificationStep, hasPhoneVerificationStep } from './config/contact';
 export { hasProofOfAddressStep, poaDocumentTypes, poaTypeLabel } from './config/proofOfAddress';
+export { hasAddressCollectionStep } from './config/addressCollection';
+// Presence verification (Address Intelligence Phase 2): the foreground
+// reporter the HOST APP calls on app open, plus the on-device pin store.
+export {
+  reportAddressPresence,
+  type ReportPresenceOptions,
+  type ReportPresenceResult,
+} from './presence/report';
+// The background (OS geofence) tier — the always-on model. register* must run
+// at app-root module scope; enable* asks for the background permission.
+export {
+  PRESENCE_GEOFENCE_TASK,
+  disableBackgroundPresence,
+  enableBackgroundPresence,
+  registerBackgroundPresence,
+  type EnableBackgroundResult,
+} from './presence/background';
+// The Android foreground-service tier (the OkHi reliability move): a
+// persistent notification keeps the process alive on phones whose battery
+// managers drop geofence transitions. Opt-in; the host words the notification.
+export {
+  PRESENCE_LOCATION_TASK,
+  disableForegroundService,
+  enableForegroundService,
+  foregroundServiceRunning,
+  type EnableForegroundServiceResult,
+  type PresenceNotification,
+} from './presence/foreground-service';
+export {
+  openLocationSettings,
+  presenceStatus,
+  type PresenceStatus,
+  type PresenceTier,
+} from './presence/status';
+export { resolvePresenceTier, type PermissionState, type TierInputs } from './presence/tier';
+// savePresencePin is the org-side handoff for STANDALONE address verification:
+// when capture happened on a hosted web link (or the org's own backend already
+// holds the address), the host app hands the SDK the pin so the foreground and
+// background presence tiers can run — the pin otherwise only ever exists where
+// OUR capture step stored it.
+export { clearPresencePin, savePresencePin } from './presence/store';
 
 // Country grouping for multi-region flows
 export { groupCountriesByRegion, regionCountryName, type Region } from './config/regions';

package/src/lib/address-current-location.ts

@@ -0,0 +1,171 @@
+import type { AddressParts } from '../services/api';
+import type { LocationFailure } from '../services/location';
+
+// ---------------------------------------------------------------------------
+// The device's current location, fetched ONCE per verification and shared by
+// every address step.
+//
+// Module-level on purpose: the steps mount and unmount as the person walks the
+// flow, and re-prompting or re-fixing on every screen is exactly the hesitation
+// this exists to remove. Every address step starts the prefetch on mount, so
+// the GPS warms up while the person is still reading the SEARCH screen; by the
+// pin step the fix — and its reverse-geocoded line — are usually already in
+// hand, and the map lands right first time instead of showing a default view
+// and then jumping.
+//
+// A MIRROR of the web SDK's steps/address/current-location.ts, with one
+// deliberate difference: web scopes the cache to a PAGE session, which ends at
+// the next reload. An app session spans many opens of the SDK, so a fix cached
+// an hour ago would drop the pin at yesterday's address. Store CREATION clears
+// it (one store per modal launch), making "this verification" the mobile
+// equivalent of that scope. Clearing it only from the store's reset() is not
+// enough: reset() is a consumer-facing restart, not part of the open path.
+// ---------------------------------------------------------------------------
+
+export interface CurrentFix {
+  lat: number;
+  lng: number;
+  accuracy: number | null;
+  /** The reverse-geocoded line ("11 Bassey Street, Calabar"), when known. */
+  label: string | null;
+  parts: AddressParts | null;
+}
+
+/** A GPS read: the fix, or WHY there is none (services/location.ts). */
+export type FixOutcome =
+  | { fix: { lat: number; lng: number; accuracy: number | null } }
+  | { failure: LocationFailure };
+
+/**
+ * What the cache needs to produce a fix.
+ *
+ * The GPS reader is INJECTED rather than imported: the store's reset clears
+ * this cache, and importing expo-location here would drag a native module into
+ * the store's graph for the sake of resetting three variables.
+ */
+export interface FixSource {
+  takeFix(): Promise<FixOutcome>;
+  addressReverse(
+    lat: number,
+    lng: number,
+  ): Promise<{ line: string | null; parts?: AddressParts | null }>;
+}
+
+let resolved: CurrentFix | null = null;
+let inflight: Promise<CurrentFix | null> | null = null;
+let failed = false;
+let lastFailure: LocationFailure | null = null;
+
+/** Why the last attempt failed, so the message can say something true. */
+export function currentFixFailure(): LocationFailure | null {
+  return lastFailure;
+}
+
+/**
+ * The message for a failed read. A refused permission, a phone that cannot
+ * place itself, and a fix that took too long are three different problems
+ * with three different remedies, and one line telling everybody to "allow
+ * location access" sent people to a permission that was already granted.
+ * Placing the pin by hand always works, so every line says so. Mirrors the
+ * web SDK's locationFailureMessage and Flutter's.
+ */
+export function locationFailureMessage(reason: LocationFailure | null): string {
+  switch (reason) {
+    case 'denied':
+      return "Location access is blocked for this app. Allow it in your phone's Settings, then try again, or place the pin yourself.";
+    case 'unavailable':
+      return 'Your phone could not work out where it is right now. Check that location is switched on, then try again, or place the pin yourself.';
+    case 'timeout':
+      return 'Finding your location took too long. Try again, or place the pin yourself.';
+    default:
+      return 'This device cannot share its location. Place the pin yourself.';
+  }
+}
+
+/** The fix, when one has already resolved for this verification. */
+export function currentFix(): CurrentFix | null {
+  return resolved;
+}
+
+/** Is a fix attempt still running? */
+export function locating(): boolean {
+  return inflight !== null && resolved === null;
+}
+
+/**
+ * Start (or JOIN) the one location attempt. Safe to call from every address
+ * step's mount: the OS permission prompt fires at most once, and a second
+ * caller waits on the first attempt rather than starting its own.
+ *
+ * Resolves null on a denied or failed read — callers fall back to the manual
+ * pin, which is what every address failure degrades to.
+ */
+export function prefetchCurrentFix(
+  source: FixSource,
+  opts?: { retry?: boolean },
+): Promise<CurrentFix | null> {
+  if (resolved) return Promise.resolve(resolved);
+  // A failed attempt (denied prompt, no fix) is never retried AUTOMATICALLY.
+  // Every step mount calls this, so re-arming on failure left the location row
+  // spinning forever and re-fired the OS prompt on each screen. An explicit
+  // TAP passes `retry` and gets a fresh attempt, since the person may have
+  // granted permission in the meantime.
+  if (failed && !inflight && !opts?.retry) return Promise.resolve(null);
+  if (!inflight) {
+    inflight = (async () => {
+      // No builder-preview branch: the preview is a web-only surface, and a
+      // canned fix here would be a code path no mobile caller can reach.
+      const outcome = await source.takeFix().catch((): FixOutcome => ({ failure: 'unsupported' }));
+      if (!('fix' in outcome)) {
+        inflight = null;
+        failed = true;
+        lastFailure = outcome.failure;
+        return null;
+      }
+      const fix = outcome.fix;
+      lastFailure = null;
+      let label: string | null = null;
+      let parts: AddressParts | null = null;
+      try {
+        const r = await source.addressReverse(fix.lat, fix.lng);
+        label = r.line ?? null;
+        parts = r.parts ?? null;
+      } catch {
+        /* the coordinates alone are still a fix */
+      }
+      resolved = { lat: fix.lat, lng: fix.lng, accuracy: fix.accuracy, label, parts };
+      failed = false;
+      return resolved;
+    })();
+  }
+  return inflight;
+}
+
+/** Forget the fix so the next verification takes its own. Called from the
+ *  store's reset, beside the step log. */
+export function resetCurrentFix(): void {
+  resolved = null;
+  inflight = null;
+  failed = false;
+  lastFailure = null;
+}
+
+// ── The pin step's automatic first locate ───────────────────────────────────
+//
+// Most people are verifying from home, so the map should land on them rather
+// than a country-centre default. It fires ONCE: a dismissed or denied prompt
+// must not re-fire every time the person passes back through the pin step, and
+// the explicit control is there for retries.
+
+let autoLocateAttempted = false;
+
+/** True the FIRST time it is called for a verification, false after. */
+export function claimAutoLocate(): boolean {
+  if (autoLocateAttempted) return false;
+  autoLocateAttempted = true;
+  return true;
+}
+
+export function resetAutoLocate(): void {
+  autoLocateAttempted = false;
+}

package/src/lib/address-field-modes.ts

@@ -0,0 +1,119 @@
+import type { AddressCollectionConfig } from '../types/workflow';
+import type { AddressState } from '../store/state';
+
+// Per-field modes for the typed details-sheet fields — the CLIENT MIRROR of
+// the server's lib/workflows/address-fields.ts (kyc-core) and of the web
+// SDK's steps/address/address-field-modes.ts. Keep the resolution rule in
+// lockstep: the legacy propertyFields group switch is the default for every
+// typed field, propertyFields 'required' requires the house/flat NUMBER, and
+// fields.<key> overrides per key. The three mirrors share one vector file
+// (kyc-sdk-flutter/test/address_field_modes_vectors.json).
+//
+// Why it matters here: the server 422s a submission whose required fields
+// never arrived. Without this mirror a mobile applicant walked the whole
+// flow, and the refusal landed on the last screen with nothing to act on.
+
+export const ADDRESS_FIELD_KEYS = [
+  'propertyName',
+  'propertyNumber',
+  'street',
+  'unit',
+  'neighbourhood',
+  'city',
+  'state',
+  'postcode',
+] as const;
+export type AddressFieldKey = (typeof ADDRESS_FIELD_KEYS)[number];
+export type AddressFieldMode = 'off' | 'optional' | 'required';
+
+export const ADDRESS_FIELD_LABELS: Record<AddressFieldKey, string> = {
+  propertyName: 'Building name',
+  propertyNumber: 'House or flat number',
+  street: 'Street name',
+  unit: 'Unit',
+  neighbourhood: 'Neighbourhood',
+  city: 'City',
+  state: 'State',
+  postcode: 'Area code',
+};
+
+const MODES: readonly string[] = ['off', 'optional', 'required'];
+function isAddressFieldMode(value: unknown): value is AddressFieldMode {
+  return typeof value === 'string' && MODES.includes(value);
+}
+
+export function addressFieldModes(
+  config: AddressCollectionConfig | undefined | null,
+): Record<AddressFieldKey, AddressFieldMode> {
+  const group = config?.propertyFields ?? 'optional';
+  const modes = {} as Record<AddressFieldKey, AddressFieldMode>;
+  for (const key of ADDRESS_FIELD_KEYS) {
+    const fallback: AddressFieldMode =
+      group === 'off' ? 'off' : group === 'required' && key === 'propertyNumber' ? 'required' : 'optional';
+    // An override outside the vocabulary falls back rather than being taken
+    // literally: the server validates writes, the client validates reads.
+    const override = config?.fields?.[key];
+    modes[key] = isAddressFieldMode(override) ? override : fallback;
+  }
+  return modes;
+}
+
+/** Which map-prefill part fills each field while untouched (the sheet's own
+ *  `shown` rule). Property name/number and unit have no prefill — the
+ *  applicant alone can know them. */
+const PART_OF: Partial<Record<AddressFieldKey, 'street' | 'area' | 'city' | 'state' | 'postcode'>> = {
+  street: 'street',
+  neighbourhood: 'area',
+  city: 'city',
+  state: 'state',
+  postcode: 'postcode',
+};
+
+/** The value the sheet DISPLAYS for a field: typed wins (a cleared field
+ *  stays cleared), else the map's prefill. */
+export function displayedAddressValue(key: AddressFieldKey, address: AddressState): string {
+  const typed = (address[key] as string | undefined)?.trim();
+  if (typed !== undefined) return typed;
+  const part = PART_OF[key];
+  return (part ? address.parts?.[part] : null)?.trim() ?? '';
+}
+
+/** Required fields whose DISPLAYED value is blank — what holds Continue. */
+export function missingRequiredAddressFields(
+  config: AddressCollectionConfig | undefined | null,
+  address: AddressState | null | undefined,
+): AddressFieldKey[] {
+  if (!address) return [];
+  const modes = addressFieldModes(config);
+  return ADDRESS_FIELD_KEYS.filter(
+    (key) => modes[key] === 'required' && displayedAddressValue(key, address) === '',
+  );
+}
+
+/** The nudge under Continue when required fields are still blank. */
+export function missingFieldsNudge(missing: AddressFieldKey[]): string {
+  return `This flow needs: ${missing.map((k) => ADDRESS_FIELD_LABELS[k].toLowerCase()).join(', ')}.`;
+}
+
+/**
+ * The map-prefill values a REQUIRED field rides to the server when the
+ * applicant left it untouched: they saw it filled and confirmed it by
+ * continuing, so the wire must carry it — the server 422s a required field
+ * that never arrives. Typed values are absent here on purpose (the normal
+ * assembly already sends them), so spreading this LAST overrides nothing.
+ */
+export function requiredPrefillSubmission(
+  config: AddressCollectionConfig | undefined | null,
+  address: AddressState,
+): Partial<Record<AddressFieldKey, string>> {
+  const modes = addressFieldModes(config);
+  const out: Partial<Record<AddressFieldKey, string>> = {};
+  for (const key of ADDRESS_FIELD_KEYS) {
+    if (modes[key] !== 'required') continue;
+    const typed = (address[key] as string | undefined)?.trim();
+    if (typed) continue;
+    const displayed = displayedAddressValue(key, address);
+    if (displayed) out[key] = displayed;
+  }
+  return out;
+}