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

package/src/services/location.ts

@@ -0,0 +1,234 @@
+// ---------------------------------------------------------------------------
+// One-shot geolocation for the address-collection step.
+//
+// Best-effort BY CONTRACT, mirroring the web SDK's address-helpers: a denied
+// permission, a device with location off, or a slow fix costs the `attested`
+// tier (or the recentre convenience) — never the flow. The attest fix resolves
+// to null / {} on any failure; the PIN's fix says WHY it failed, so the copy
+// can send the person to the right remedy (see lib/address-current-location).
+// ---------------------------------------------------------------------------
+
+import * as Location from 'expo-location';
+
+const FIX_TIMEOUT_MS = 8_000;
+
+/** Accuracy at which a fix is good enough to stop waiting for the GPS. */
+const PRECISE_ENOUGH_M = 25;
+const PRECISE_WINDOW_MS = 8_000;
+/**
+ * Once ANY fix exists, wait only this much longer for a better one. An indoor
+ * or wifi-derived fix never reaches 25m, and sitting out the whole window for
+ * an accuracy that is not coming reads as "it keeps loading".
+ */
+const FIRST_FIX_GRACE_MS = 3_000;
+
+export interface DeviceFix {
+  lat: number;
+  lng: number;
+  accuracy: number | null;
+  timestamp: number;
+  /** Android reports a mock-location provider; iOS has no equivalent (null). */
+  mocked: boolean | null;
+}
+
+/**
+ * Why a fix could not be taken. A refused permission, a phone that cannot
+ * place itself (location switched off, no provider), and a fix that took
+ * longer than the window are three different problems with three different
+ * remedies. Mirrors the web SDK's LocationFailure and Flutter's enum.
+ */
+export type LocationFailure = 'denied' | 'unavailable' | 'timeout' | 'unsupported';
+
+export type PreciseFixOutcome = { fix: DeviceFix } | { failure: LocationFailure };
+
+function toFix(pos: Location.LocationObject): DeviceFix {
+  return {
+    lat: pos.coords.latitude,
+    lng: pos.coords.longitude,
+    accuracy: typeof pos.coords.accuracy === 'number' ? pos.coords.accuracy : null,
+    timestamp: pos.timestamp || Date.now(),
+    mocked: typeof pos.mocked === 'boolean' ? pos.mocked : null,
+  };
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('location timeout')), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+// The most recent fix ANY read produced, kept so the confirm-time attest read
+// can fall back on it (see deviceFixFields).
+let lastGoodFix: DeviceFix | null = null;
+function remember(fix: DeviceFix): DeviceFix {
+  lastGoodFix = fix;
+  return fix;
+}
+
+/** A fix older than this no longer says where the phone is NOW. */
+export const LAST_KNOWN_MAX_AGE_MS = 10 * 60_000;
+
+/**
+ * One fix for a presence report, or null. Asks for foreground permission on
+ * first use.
+ *
+ * Resolves the way the pin step's precise read learned to, in three rungs:
+ * a fresh read at BALANCED accuracy (the fence is 250m or wider, so a 100m
+ * fix is plenty; Expo's iOS read waits for a fix that MEETS the requested
+ * accuracy, and a High request indoors never delivered one inside the
+ * window, so every RN report on the iPhone came back `no_fix` while
+ * Flutter's Geolocator, which returns the first update, reported fine,
+ * 2026-09-08), then the platform's last known position, then the last fix
+ * this module itself took (the pin step's, minutes earlier), each accepted
+ * only within LAST_KNOWN_MAX_AGE_MS. Flutter's reporter carries the same
+ * last-known fallback.
+ */
+export async function currentPosition(): Promise<DeviceFix | null> {
+  try {
+    const { status } = await Location.requestForegroundPermissionsAsync();
+    if (status !== 'granted') return null;
+  } catch {
+    return null;
+  }
+  const fresh = await withTimeout(
+    Location.getCurrentPositionAsync({ accuracy: Location.Accuracy.Balanced }),
+    FIX_TIMEOUT_MS,
+  ).then(toFix, () => null);
+  if (fresh) return remember(fresh);
+  const known = await Location.getLastKnownPositionAsync({ maxAge: LAST_KNOWN_MAX_AGE_MS }).then(
+    (pos) => (pos ? toFix(pos) : null),
+    () => null,
+  );
+  if (known) return remember(known);
+  if (lastGoodFix && Date.now() - lastGoodFix.timestamp <= LAST_KNOWN_MAX_AGE_MS) return lastGoodFix;
+  return null;
+}
+
+/**
+ * A PRECISE fix: watch the position for up to ~8s, keep the most accurate
+ * reading, and resolve early once it is within 25m.
+ *
+ * A single `getCurrentPositionAsync` routinely answers with the first coarse
+ * wifi/cell reading — hundreds of metres out, before the GPS has warmed up —
+ * which is exactly the pin landing on the wrong compound. A WATCH also never
+ * hands back a cached fix, which is the other half of what a pin needs.
+ *
+ * Never throws: every failure is CLASSIFIED, and every caller falls back to
+ * placing the pin by hand.
+ */
+export async function precisePositionOutcome(): Promise<PreciseFixOutcome> {
+  let granted = false;
+  try {
+    const { status } = await Location.requestForegroundPermissionsAsync();
+    granted = status === 'granted';
+  } catch {
+    // No location module behind the call: nothing on this device can answer.
+    return { failure: 'unsupported' };
+  }
+  if (!granted) return { failure: 'denied' };
+  try {
+    // Permission granted with the toggle OFF is the failure people hit most,
+    // and it is the one "allow location access" sends them the wrong way on.
+    if (!(await Location.hasServicesEnabledAsync())) return { failure: 'unavailable' };
+  } catch {
+    // An older module without the probe: let the watch decide.
+  }
+
+  return new Promise<PreciseFixOutcome>((resolve) => {
+    let best: Location.LocationObject | null = null;
+    let settled = false;
+    let watchFailed = false;
+    let sub: Location.LocationSubscription | null = null;
+    let grace: ReturnType<typeof setTimeout> | null = null;
+
+    const finish = (): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(windowTimer);
+      if (grace) clearTimeout(grace);
+      sub?.remove();
+      if (best) resolve({ fix: remember(toFix(best)) });
+      else resolve({ failure: watchFailed ? 'unavailable' : 'timeout' });
+    };
+
+    const windowTimer = setTimeout(finish, PRECISE_WINDOW_MS);
+
+    Location.watchPositionAsync(
+      { accuracy: Location.Accuracy.BestForNavigation, distanceInterval: 0 },
+      (pos) => {
+        const acc = pos.coords.accuracy ?? Infinity;
+        if (!best || acc < (best.coords.accuracy ?? Infinity)) best = pos;
+        if (acc <= PRECISE_ENOUGH_M) {
+          finish();
+          return;
+        }
+        if (!grace) grace = setTimeout(finish, FIRST_FIX_GRACE_MS);
+      },
+    )
+      .then((subscription) => {
+        // The window may already have elapsed while the watch was starting —
+        // hold no subscription nobody will ever remove.
+        if (settled) subscription.remove();
+        else sub = subscription;
+      })
+      .catch(() => {
+        watchFailed = true;
+        finish();
+      });
+  });
+}
+
+/**
+ * The attest-presence device fix, as the fields the verify body carries.
+ * Empty when no fix could be taken — the submission simply goes without the
+ * `attested` tier.
+ */
+/** How old a fix from earlier in the SAME address flow may be and still stand
+ *  in for the confirm-time read. Placing a pin takes a minute or two; a fix
+ *  from that window still says the device was here, and the server judges it
+ *  by its own `capturedAt` anyway. */
+export const RECENT_FIX_MAX_AGE_MS = 3 * 60_000;
+
+/** The reading the attest step should send: a fresh one when the read
+ *  answered, else the recent one the flow already took, else nothing. Pure,
+ *  so the rule is testable without a GPS. */
+export function pickDeviceFix(
+  fresh: DeviceFix | null,
+  recent: DeviceFix | null,
+  now: number = Date.now(),
+): DeviceFix | null {
+  if (fresh) return fresh;
+  if (recent && now - recent.timestamp <= RECENT_FIX_MAX_AGE_MS && recent.mocked !== true) return recent;
+  return null;
+}
+
+export async function deviceFixFields(): Promise<{
+  deviceLat?: number;
+  deviceLng?: number;
+  deviceAccuracy?: number;
+  capturedAt?: string;
+}> {
+  // A single getCurrentPositionAsync at confirm routinely times out on iOS
+  // while the GPS is still settling, and the submission then went out with
+  // no fix at all even though "Use my location" had just placed the pin on
+  // one (iPhone 16 Pro Max, 2026-09-07: every address run read "No device
+  // fix taken"). The fix the flow already holds is the fallback.
+  const fix = pickDeviceFix(await currentPosition(), lastGoodFix);
+  if (!fix) return {};
+  return {
+    deviceLat: fix.lat,
+    deviceLng: fix.lng,
+    ...(fix.accuracy != null ? { deviceAccuracy: fix.accuracy } : {}),
+    capturedAt: new Date(fix.timestamp).toISOString(),
+  };
+}

package/src/services/uploadErrors.ts

@@ -0,0 +1,30 @@
+import { KYCApiError } from './api';
+import { UPLOAD_HINT } from '../config/uploadLimits';
+
+// ---------------------------------------------------------------------------
+// Why an upload failed, in words the person can act on.
+//
+// Every upload used to fail as "we could not upload that document", which tells
+// the applicant nothing about whether to pick a smaller file, a different
+// format, or simply try again on better signal. The server already says which
+// it is; this reads its answer and hands back the sentence that matches.
+// ---------------------------------------------------------------------------
+
+/** The refusal, as something the applicant can do something about. */
+export function uploadFailureMessage(error: unknown): string {
+  const status = error instanceof KYCApiError ? error.statusCode : null;
+  const raw = error instanceof Error ? error.message.toLowerCase() : '';
+
+  if (status === 413 || raw.includes('too large')) {
+    return `That file is too large. ${UPLOAD_HINT}`;
+  }
+  if (raw.includes('mimetype') || raw.includes('mime type') || raw.includes('unsupported')) {
+    return `That file type is not supported. ${UPLOAD_HINT}`;
+  }
+  // A 4xx we have no better words for still says the file is the problem, so
+  // the person retries with a DIFFERENT one rather than the same one twice.
+  if (status !== null && status >= 400 && status < 500) {
+    return `We could not read that file. ${UPLOAD_HINT}`;
+  }
+  return 'We could not upload that document. Please check your connection and try again.';
+}

package/src/services/workflowGate.ts

@@ -103,6 +103,13 @@ export async function resolveWorkflow(
         idTypes: res.idTypes,
         branding: res.branding,
         geoCountry: res.geoCountry,
+        // The resolution route does not serve these yet, so a workflow mount
+        // reads undefined and the address flow offers no search screen. That
+        // degrades correctly, and the passthrough means it starts working the
+        // day the server carries them.
+        addressSearch: res.addressSearch,
+        addressSearchMode: res.addressSearchMode,
+        mapsFrameUrl: res.mapsFrameUrl ?? null,
         environment: res.environment,
         fatal: false,
       },

package/src/store/address.ts

@@ -0,0 +1,97 @@
+import type { AddressState } from './state';
+
+// ---------------------------------------------------------------------------
+// Restoring a saved address pin.
+//
+// The whole address object is written into session progress verbatim, so the
+// snapshot was written by WHATEVER build saved it: coerce every field back to
+// its declared type and degrade to restoring less, never to breaking the flow.
+//
+// Deliberately does NOT restore the device fix (deviceLat / deviceLng /
+// deviceAccuracy / capturedAt). That is the attest-presence reading, and it is
+// taken fresh at confirm — a stale one would claim the applicant stood at the
+// address on a day they did not.
+//
+// Split from session.ts per the 200-line rule. A MIRROR of the web SDK's
+// RESTORE_PROGRESS address branch and the Flutter port.
+// ---------------------------------------------------------------------------
+
+function str(v: unknown): string | null {
+  return typeof v === 'string' ? v : null;
+}
+
+/** The `parts` breakdown, when the snapshot carries an object for it. */
+function restoreParts(v: unknown): Pick<AddressState, 'parts'> {
+  if (!v || typeof v !== 'object') return {};
+  const p = v as Record<string, unknown>;
+  return {
+    parts: {
+      street: str(p['street']),
+      area: str(p['area']),
+      city: str(p['city']),
+      state: str(p['state']),
+      postcode: str(p['postcode']),
+      country: str(p['country']),
+    },
+  };
+}
+
+/** The picked-label anchor, only when it is a real coordinate pair. */
+function restorePickedAt(v: unknown): Pick<AddressState, 'pickedAt'> {
+  if (!v || typeof v !== 'object') return {};
+  const p = v as Record<string, unknown>;
+  return typeof p['lat'] === 'number' && typeof p['lng'] === 'number'
+    ? { pickedAt: { lat: p['lat'], lng: p['lng'] } }
+    : {};
+}
+
+/** The Street View frame, only when every field of it survived. A partial
+ *  frame cannot be re-rendered, and half of one is not a capture. */
+function restoreStreetView(v: unknown): Pick<AddressState, 'streetView'> {
+  if (!v || typeof v !== 'object') return {};
+  const sv = v as Record<string, unknown>;
+  return typeof sv['panoId'] === 'string' &&
+    typeof sv['heading'] === 'number' &&
+    typeof sv['pitch'] === 'number' &&
+    typeof sv['fov'] === 'number'
+    ? {
+        streetView: {
+          panoId: sv['panoId'],
+          heading: sv['heading'],
+          pitch: sv['pitch'],
+          fov: sv['fov'],
+        },
+      }
+    : {};
+}
+
+/**
+ * Rebuild the address from a progress snapshot. The caller has already checked
+ * that `lat` and `lng` are numbers — without those there is no pin, and there
+ * is nothing to restore.
+ */
+export function restoreAddress(a: Record<string, unknown>): AddressState {
+  return {
+    lat: a['lat'] as number,
+    lng: a['lng'] as number,
+    accuracy: typeof a['accuracy'] === 'number' ? a['accuracy'] : null,
+    directions: typeof a['directions'] === 'string' ? a['directions'] : '',
+    propertyName: typeof a['propertyName'] === 'string' ? a['propertyName'] : '',
+    propertyNumber: typeof a['propertyNumber'] === 'string' ? a['propertyNumber'] : '',
+    // The resolved line and its breakdown survive a restart too. Dropping them
+    // is why a resumed session showed raw coordinates where the applicant had
+    // picked an address.
+    ...(typeof a['label'] === 'string' ? { label: a['label'] } : {}),
+    ...(typeof a['street'] === 'string' ? { street: a['street'] } : {}),
+    // The edit-details claims survive a restart like every other typed field.
+    ...(typeof a['unit'] === 'string' ? { unit: a['unit'] } : {}),
+    ...(typeof a['neighbourhood'] === 'string' ? { neighbourhood: a['neighbourhood'] } : {}),
+    ...(typeof a['city'] === 'string' ? { city: a['city'] } : {}),
+    ...(typeof a['state'] === 'string' ? { state: a['state'] } : {}),
+    ...(typeof a['postcode'] === 'string' ? { postcode: a['postcode'] } : {}),
+    ...(a['labelKept'] === true ? { labelKept: true } : {}),
+    ...restorePickedAt(a['pickedAt']),
+    ...restoreParts(a['parts']),
+    ...restoreStreetView(a['streetView']),
+  };
+}

package/src/store/derive.ts

@@ -7,14 +7,19 @@
 // keeps a single answer to each of those questions.
 // ---------------------------------------------------------------------------
 
+import { configScope } from '../lib/scope';
 import { requiresDocumentCapture, supportsNfcChip } from '../config/idTypes';
 import {
+  buildStepOrder,
   getStepProgress,
   nextStepInOrder,
   previousStepInOrder,
   type StepOrderOptions,
 } from '../config/stepOrder';
 import { hasProofOfAddressStep } from '../config/proofOfAddress';
+import { addressFlowFor, hasAddressCollectionStep } from '../config/addressCollection';
+import { webViewAvailable } from '../lib/webview-available';
+import { addressVendorsStubbed } from '../lib/address-flow';
 import { businessProductsForCountry, isBusinessFlow } from '../config/business';
 import {
   hasApplicantVerification,
@@ -22,6 +27,7 @@ import {
   hasKeyPeopleCollection,
 } from '../config/businessSteps';
 import { hasActiveQuestionnaire } from '../config/questionnaire';
+import { hasConsentStep, openingStepOf } from '../config/consentStep';
 import { applicantSelfCountry, keyPeoplePayload } from '../config/keyPeople';
 import { featuresFor } from './serverConfig';
 import type { VerifyRequest } from '../services/api';
@@ -58,6 +64,7 @@ export function stepOrderOptions(state: KycState): StepOrderOptions {
   const idType = state.selectedIdType;
   return {
     isBusiness: isBusinessFlow(config),
+    scope: configScope(config),
     business: config.business,
     hasDocCapture: idType ? requiresDocumentCapture(idType) : true,
     hasNfc: nfcEnabled(state),
@@ -72,9 +79,20 @@ export function stepOrderOptions(state: KycState): StepOrderOptions {
     hasCountrySelect:
       countrySelectOptions(state).length > 1 &&
       applicantSelfCountry(state.businessApplication) === null,
+    hasConsent: hasConsentStep(config),
     hasEmailVerification: config.emailVerification?.enabled === true,
     hasPhoneVerification: config.phoneVerification?.enabled === true,
     hasPoa: hasProofOfAddressStep(config.proofOfAddress),
+    hasAddressCollection: hasAddressCollectionStep(config.addressCollection),
+    // An absent search flag means no search SCREEN, never an error: the
+    // applicant places the pin by hand, the fallback every address failure
+    // degrades to.
+    addressFlow: addressFlowFor(
+      config,
+      state.serverConfig.addressSearch === true,
+      addressVendorsStubbed({ environment: state.serverConfig.environment }),
+      Boolean(state.serverConfig.mapsFrameUrl) && webViewAvailable(),
+    ),
     hasQuestionnaire: hasActiveQuestionnaire(config.questionnaire),
     // Present only on a session a reviewer sent back. Narrows the order to the
     // steps they ticked, so somebody fixing one blurry photo is not walked
@@ -237,11 +255,18 @@ export function previousStepBefore(step: KYCStep, state: KycState): KYCStep {
   return previousStepInOrder(step, stepOrderOptions(state));
 }
 
+/**
+ * The step this flow OPENS on: 'consent', or the first real step when the
+ * workflow switched the consent screen off (`consentStep: false`). The store
+ * starts and resets here, the progress watcher judges "untouched" against it,
+ * and the flow hides Back on it. Never depends on anything the applicant has
+ * yet to choose: only later steps do.
+ */
+export function openingStep(state: KycState): KYCStep {
+  return openingStepOf(buildStepOrder(stepOrderOptions(state)));
+}
+
 /** Percentage complete, for the sheet's progress indicator. */
 export function stepProgress(step: KYCStep, state: KycState): number {
   return getStepProgress(step, stepOrderOptions(state));
 }
-
-// ---------------------------------------------------------------------------
-// Store factory
-// ---------------------------------------------------------------------------

package/src/store/kycStore.ts

@@ -27,7 +27,7 @@ import {
   type KycState,
   type KycStore,
 } from './state';
-import { nextStepAfter, nfcDecision, previousStepBefore } from './derive';
+import { nextStepAfter, nfcDecision, openingStep, previousStepBefore } from './derive';
 
 /** The steps that make up ONE ID's evidence. Leaving this set is what ends a
  *  multi-ID check — the leg has several exits depending on the ID. */
@@ -54,9 +54,11 @@ function multiIdPlanFor(s: KycState): ReturnType<typeof multiIdPlan> {
   );
 }
 import { recordStep, resetStepLog } from '../lib/step-log';
+import { resetAutoLocate, resetCurrentFix } from '../lib/address-current-location';
 import { multiIdPlan } from '../lib/multi-id';
 import { resolveIdTypeDefinition } from '../config/idTypes';
 import { buildVerifyRequest } from './submit';
+import { IDLE_SELFIE_UPLOAD } from '../lib/selfie-upload-wait';
 import { resetBusinessCheck, runBusinessCheck } from './businessCheck';
 import { startAttemptSession, watchSessionProgress } from './session';
 import { applicantMediaCaptured, buildApplicantVerifyRequest } from './submitApplicant';
@@ -99,11 +101,14 @@ export function createKycStore(
       sessionUrl: null,
       businessCheck: { ...EMPTY_BUSINESS_CHECK },
       selectedCountry: null,
+      countryAutoPicked: false,
       selectedIdType: null,
       idNumber: null,
       multiIdSlotIndex: 0,
       multiIdSlots: [],
       multiIdRestored: null,
+      selfiePreviewUri: null,
+      selfieUpload: IDLE_SELFIE_UPLOAD,
       mediaIds: {},
       submissionResult: null,
       serverConfig: serverConfig ?? INITIAL_SERVER_CONFIG,
@@ -124,6 +129,11 @@ export function createKycStore(
       chipData: null,
       poaDocumentType: null,
       poaFileName: null,
+      address: null,
+      addressPhotoPreview: null,
+      addressIntroSeen: false,
+      addressEntranceFraming: false,
+      addressSandboxOutcome: null,
       isLoading: false,
       error: null,
 
@@ -137,16 +147,27 @@ export function createKycStore(
           const branding = res.branding
             ? { ...res.branding, logo: normalizeDevAssetUrl(res.branding.logo, baseUrl) }
             : res.branding;
+          // The facts that just landed can add a step AHEAD of the one the flow
+          // opened on (the address search step, on a consent-less address
+          // flow). Someone still standing on the placeholder's opening step,
+          // having done nothing, is moved to the real one; anyone who has
+          // moved is left alone. Mirrors Flutter's _loadServerConfig.
+          const before = openingStep(get());
           set({
             serverConfig: {
               status: 'ready',
               idTypes: res.idTypes,
               branding,
               geoCountry: res.geoCountry,
+              addressSearch: res.addressSearch,
+              addressSearchMode: res.addressSearchMode,
+              mapsFrameUrl: res.mapsFrameUrl ?? null,
               environment: res.environment,
               fatal: false,
             },
           });
+          const after = openingStep(get());
+          if (get().currentStep === before && after !== before) set({ currentStep: after });
         } catch (err) {
           const described = describeConfigError(err);
           set((s) => ({
@@ -163,6 +184,7 @@ export function createKycStore(
           const same = s.selectedCountry === country;
           return {
             selectedCountry: country,
+            countryAutoPicked: false,
             selectedIdType: same ? s.selectedIdType : null,
             idNumber: same ? s.idNumber : null,
             // A multi-ID run's committed slots belong to the country they were
@@ -175,6 +197,11 @@ export function createKycStore(
         });
       },
 
+      setCountryAuto(country) {
+        get().setCountry(country);
+        if (!get().countryAutoPicked) set({ countryAutoPicked: true });
+      },
+
       commitMultiIdSlot(nextStep, previews) {
         set((s) => {
           if (!s.selectedIdType) return {};
@@ -257,6 +284,22 @@ export function createKycStore(
         set((s) => ({ mediaIds: { ...s.mediaIds, [key]: mediaId } }));
       },
 
+      setSelfiePreview(uri) {
+        set({ selfiePreviewUri: uri });
+      },
+
+      clearSelfie() {
+        set((s) => ({
+          selfiePreviewUri: null,
+          selfieUpload: IDLE_SELFIE_UPLOAD,
+          mediaIds: { ...s.mediaIds, selfie: undefined, livenessVideo: undefined },
+        }));
+      },
+
+      setSelfieUpload(upload) {
+        set({ selfieUpload: upload });
+      },
+
       setDocumentMediaId(mediaId, side) {
         set((s) => ({
           mediaIds: {
@@ -423,6 +466,41 @@ export function createKycStore(
         });
       },
 
+      setAddress(address) {
+        set({ address });
+      },
+
+      setAddressSandboxOutcome(addressSandboxOutcome) {
+        set({ addressSandboxOutcome });
+      },
+
+      setAddressPhoto(mediaId) {
+        set((s) => {
+          if (mediaId) return { mediaIds: { ...s.mediaIds, addressPhoto: mediaId } };
+          const { addressPhoto: _dropped, ...rest } = s.mediaIds;
+          return { mediaIds: rest };
+        });
+      },
+
+      setAddressPhotoPreview(uri) {
+        set({ addressPhotoPreview: uri });
+      },
+
+      markAddressIntroSeen() {
+        set({ addressIntroSeen: true });
+      },
+
+      setAddressEntranceFraming(framing) {
+        if (get().addressEntranceFraming !== framing) set({ addressEntranceFraming: framing });
+      },
+
+      clearAddress() {
+        set((s) => {
+          const { addressPhoto: _dropped, ...rest } = s.mediaIds;
+          return { address: null, mediaIds: rest, addressPhotoPreview: null };
+        });
+      },
+
       setDocumentCapturePhase(phase) {
         if (get().documentCapturePhase !== phase) set({ documentCapturePhase: phase });
       },
@@ -569,15 +647,27 @@ export function createKycStore(
         // already sitting on 'consent' (the subscribe below only fires on
         // change, and recordStep dedupes if it fires too).
         resetStepLog();
-        recordStep('consent', multiIdSlotOf(get()), selectedIdTypeOf(get()));
+        // The cached GPS fix and the once-per-verification auto-locate are
+        // scoped to ONE verification: an app session spans many opens of the
+        // SDK, and a fix taken an hour ago would drop the pin at wherever the
+        // phone was then.
+        resetCurrentFix();
+        resetAutoLocate();
+        // The opening step never depends on the fields reset below (only later
+        // steps do), so it is safe to read before the write.
+        const opening = openingStep(get());
+        recordStep(opening, multiIdSlotOf(get()), selectedIdTypeOf(get()));
         set({
-          currentStep: 'consent',
+          currentStep: opening,
           selectedCountry: null,
+          countryAutoPicked: false,
           selectedIdType: null,
           idNumber: null,
           multiIdSlotIndex: 0,
           multiIdSlots: [],
           multiIdRestored: null,
+          selfiePreviewUri: null,
+          selfieUpload: IDLE_SELFIE_UPLOAD,
           mediaIds: {},
           submissionResult: null,
           documentScanPhase: 'front',
@@ -599,6 +689,11 @@ export function createKycStore(
           chipData: null,
           poaDocumentType: null,
           poaFileName: null,
+          address: null,
+          addressPhotoPreview: null,
+          addressIntroSeen: false,
+      addressEntranceFraming: false,
+      addressSandboxOutcome: null,
           isLoading: false,
           error: null,
         });
@@ -622,6 +717,20 @@ export function createKycStore(
   // subscription above only fires on CHANGE, and a new store already sits on
   // 'consent').
   resetStepLog();
+  // The module-level GPS cache and the auto-locate latch are scoped to ONE
+  // verification, and this — not reset() — is where a verification begins.
+  // Clearing them only in reset() left both alive across modal launches, so a
+  // second verification in the same app session dropped its pin wherever the
+  // phone had been on the first (possibly hours and a city away) and skipped
+  // the automatic locate entirely, since the latch was already spent.
+  resetCurrentFix();
+  resetAutoLocate();
+  // A workflow that switched the consent screen off opens on its first real
+  // step; the literal 'consent' above is only the shape before the config is
+  // consulted. Set BEFORE the journey is recorded, so the log opens where the
+  // person does.
+  const opening = openingStep(store.getState());
+  if (opening !== store.getState().currentStep) store.setState({ currentStep: opening });
   recordStep(
     store.getState().currentStep,
     multiIdSlotOf(store.getState()),