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

package/src/services/api-verify-types.ts

@@ -10,7 +10,26 @@
 export interface VerifyRequest {
   country: string;
   idType: string;
+  /** The attempt session this run happened under — the verification adopts its
+   *  id, and a registry check paid at selection is not paid again at submit. */
+  sessionId?: string;
   idNumber?: string;
+  /**
+   * Multi-ID: every check in the run, in pick order (2–3). ONE verification
+   * comes back, judged by the workflow's pass policy. The top-level
+   * idType/idNumber mirror the first entry.
+   */
+  idChecks?: Array<{
+    idType: string;
+    idNumber?: string;
+    documentFront?: string;
+    documentBack?: string;
+    /** Each check's OWN document recording. */
+    documentFrontVideo?: string;
+    documentBackVideo?: string;
+    /** This check's own chip read — the chip belongs to a PARTICULAR document. */
+    nfc?: VerifyRequest['nfc'];
+  }>;
   /** The org's user reference → Entity.externalUserId at the seam (not matched). */
   userId?: string;
   userData?: {
@@ -26,9 +45,46 @@ export interface VerifyRequest {
     documentBackVideo?: string;
     livenessVideo?: string;
     proofOfAddress?: string;
+    /** Address Intelligence door photo (individual flows only). */
+    addressPhoto?: string;
   };
   /** Which kind of document the user said they uploaded as proof of address. */
   proofOfAddressType?: string;
+  /**
+   * Address Intelligence: the map pin the applicant dropped (+ the optional
+   * one-shot device fix taken at Continue). The server corroborates it; the
+   * SDK only collects. Sent only when the step ran and a pin was confirmed.
+   */
+  address?: {
+    lat: number;
+    lng: number;
+    accuracy?: number;
+    /**
+     * The line the applicant CONFIRMED (a search pick, or a reverse geocode
+     * they accepted). The server prefers it for the composed address over its
+     * own derivation, whose OSM coverage drops whole streets in our markets.
+     */
+    label?: string;
+    directions?: string;
+    propertyName?: string;
+    propertyNumber?: string;
+    /** A street the applicant typed because no map source knew it. */
+    street?: string;
+    /** The edit-details claims: unit + area/region corrections. */
+    unit?: string;
+    neighbourhood?: string;
+    city?: string;
+    state?: string;
+    postcode?: string;
+    /** Street View entrance frame — coordinates only; the server fetches the
+     *  image with its own key. Never written by this SDK (no panorama on
+     *  mobile), but a session begun on a hosted page can carry one. */
+    streetView?: { panoId: string; heading: number; pitch: number; fov: number };
+    deviceLat?: number;
+    deviceLng?: number;
+    deviceAccuracy?: number;
+    capturedAt?: string;
+  };
   /**
    * Business (KYB) registry details. Its presence is what makes this a business
    * submission — and the server REQUIRES a published KYB workflow for one, so
@@ -50,6 +106,13 @@ export interface VerifyRequest {
     email?: string;
     phone?: string;
     website?: string;
+    /** Registry facts the applicant states (the extended collectCompanyInfo
+     *  fields) — where they differ from the register, that is the finding. */
+    dateOfIncorporation?: string;
+    taxId?: string;
+    vatNumber?: string;
+    companyType?: string;
+    natureOfBusiness?: string;
     /** Uploaded supporting documents (honoured only when the workflow's
      *  `business.documents` block configures them). */
     documents?: Array<{ type: string; mediaId: string }>;
@@ -77,7 +140,33 @@ export interface VerifyRequest {
    * signer — and only the server may conclude a chip is genuine. `chipAuth`
    * reports how the chip was unlocked and is informational.
    */
-  nfc?: { dg1: string; sod?: string; dg2?: string; chipAuth?: string };
+  nfc?: {
+    dg1: string;
+    sod?: string;
+    dg2?: string;
+    dg7?: string;
+    dg11?: string;
+    dg12?: string;
+    /**
+     * DG15 (the chip's Active-Authentication public key) and its signature over
+     * the challenge the server issued — the ANTI-CLONE proof. Passive
+     * authentication proves the issuing state signed this data; only these
+     * prove it is the chip they signed it onto. Verified server-side against a
+     * SOD-bound DG15: a client that checked its own chip could be patched.
+     */
+    dg15?: string;
+    aaChallengeId?: string;
+    aaSignature?: string;
+    chipAuth?: string;
+    /**
+     * WHY the session is on that protocol. A chip reading over BAC because it
+     * offers no PACE is nothing to act on; one reading over BAC because our
+     * PACE broke is a bug, and `chipAuth` alone cannot tell them apart.
+     * Diagnostic only — the server records it and never judges on it.
+     */
+    paceOutcome?: string;
+    paceDetail?: string;
+  };
   /** The workflow that drove this flow — attributes the submission to it. */
   workflowId?: string;
   /**

package/src/services/api.ts

@@ -1,10 +1,20 @@
 import { SDK_VERSION } from './deviceMetadata';
 import type {
+  AddressReverseResult,
+  AddressSearchHit,
+  BusinessRegionsResponse,
+  BusinessSearchResponse,
+  BusinessSelectResponse,
   ContactCheckResponse,
+  NfcChallengeResponse,
   ContactSendResponse,
   HealthResponse,
   MediaUploadType,
+  PlaceSuggestion,
+  ResolvedPlace,
   SdkConfigResponse,
+  SessionStartResponse,
+  SessionSummaryResponse,
   UploadFile,
   UploadResponse,
   VerificationStatusResponse,
@@ -12,6 +22,7 @@ import type {
   VerifyResponse,
   WorkflowResolutionResponse,
 } from './api-types';
+import { biometricCalls } from './api-biometric';
 
 // The HTTP contract lives in ./api-types and is re-exported here, so importers
 // keep a single entry point for both the client and the shapes it exchanges.
@@ -64,9 +75,14 @@ function uriToBlob(uri: string, mimeType: string): Promise<Blob> {
     xhr.onload = () => {
       const blob = xhr.response as Blob | null;
       if (blob) {
-        // Ensure the part carries the right content-type even if the platform
-        // didn't infer one from the URI.
-        resolve(blob.type ? blob : blob.slice(0, blob.size, mimeType));
+        // ALWAYS re-type the part, never only when the platform inferred
+        // nothing. Its guess comes from the URI's extension and describes the
+        // file we PICKED, not the one we are sending: an iPhone gallery photo
+        // arrives as HEIC, gets transcoded to JPEG on the way here, and the
+        // part still went out labelled image/heic — which the server refuses,
+        // so most camera-roll uploads failed with a message that blamed the
+        // document. `mimeType` is the normalised type the bytes actually are.
+        resolve(blob.type === mimeType ? blob : blob.slice(0, blob.size, mimeType));
       } else {
         reject(new Error(`Could not read file at ${uri}`));
       }
@@ -151,6 +167,8 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
   }
 
   return {
+    ...biometricCalls(request),
+
     /**
      * Single multipart upload: the local file is POSTed to our server, which
      * stores it and returns the `mediaId` referenced later by /verify.
@@ -234,6 +252,18 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       });
     },
 
+    /**
+     * A fresh Active-Authentication challenge for a chip read — the nonce the
+     * chip signs to prove it is the original document rather than a copy of
+     * one. It has to come from the SERVER: a nonce the client chose would let
+     * a captured signature be replayed forever, which is the clone the check
+     * exists to catch. Best-effort by contract at every call site — a chip
+     * read without one is exactly the read we did before.
+     */
+    async nfcChallenge(): Promise<NfcChallengeResponse> {
+      return request<NfcChallengeResponse>('/nfc/challenge', { method: 'POST' });
+    },
+
     async config(signal?: AbortSignal): Promise<SdkConfigResponse> {
       return request<SdkConfigResponse>('/config', signal ? { signal } : {});
     },
@@ -250,6 +280,210 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       );
     },
 
+    /**
+     * Begin (or resume) a verification ATTEMPT session. Best-effort by
+     * contract: sessions power resumability, the dashboard's live attempt
+     * view, and the registry check at selection — verifying is never
+     * conditional on one existing.
+     */
+    async startSession(input: {
+      externalUserId?: string;
+      workflowId?: string;
+      /** Persistent device id — the anonymous-mount resume fallback. */
+      deviceRef?: string;
+      /** The same device block the submission sends, so the dashboard's
+       *  in-progress row shows the device and SDK from the moment the SDK
+       *  loads rather than after the applicant finishes (2026-09-08). */
+      device?: Record<string, unknown>;
+    }): Promise<SessionStartResponse> {
+      return request<SessionStartResponse>('/session/start', {
+        method: 'POST',
+        body: JSON.stringify(input),
+      });
+    },
+
+    /**
+     * A submitted session, rebuilt server-side — the reconciled key-people
+     * list the success screen polls. Same body a hosted link reads by token,
+     * so mobile and hosted success screens cannot tell different stories
+     * about one application.
+     */
+    async sessionSummary(sessionId: string): Promise<SessionSummaryResponse> {
+      return request<SessionSummaryResponse>(`/session/${sessionId}/summary`);
+    },
+
+    /**
+     * Save where the user has got to. Losing a save costs some re-typing on
+     * resume and must never interrupt them now — callers swallow failures.
+     */
+    async saveProgress(sessionId: string, progress: unknown): Promise<void> {
+      await request(`/session/${encodeURIComponent(sessionId)}/progress`, {
+        method: 'PUT',
+        body: JSON.stringify(progress),
+      });
+    },
+
+    /**
+     * Find a business by name. FREE — no provider charge here or upstream, so
+     * the applicant may look as many times as they need. Throws on a provider
+     * failure so the caller can show "unavailable" rather than an empty list,
+     * which would read as "this business is not registered".
+     */
+    async businessSearch(params: {
+      country: string;
+      subdivisionCode?: string;
+      query: string;
+      limit?: number;
+    }): Promise<BusinessSearchResponse> {
+      const qs = new URLSearchParams({ country: params.country, query: params.query });
+      if (params.subdivisionCode) qs.set('subdivisionCode', params.subdivisionCode);
+      if (params.limit) qs.set('limit', String(params.limit));
+      return request<BusinessSearchResponse>(`/business/search?${qs.toString()}`);
+    },
+
+    /** Registry regions for a country. Empty when it has a single register. */
+    async businessRegions(country: string): Promise<BusinessRegionsResponse> {
+      return request<BusinessRegionsResponse>(
+        `/business/regions?country=${encodeURIComponent(country)}`,
+      );
+    },
+
+    /**
+     * The PAID registry check for the company the applicant identified, run at
+     * selection so the register's key people come back BEFORE the form asks
+     * for them. Never fails the flow: a short balance, unconfigured pricing or
+     * a spent lookup budget returns `checked: false` and the lookup happens at
+     * submit as before.
+     */
+    async businessSelect(body: {
+      sessionId: string;
+      country: string;
+      subdivisionCode?: string;
+      product?: string;
+      registrationNumber: string;
+      registrationName?: string;
+      sandboxOutcome?: string;
+    }): Promise<BusinessSelectResponse> {
+      return request<BusinessSelectResponse>('/business/select', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+    },
+
+    /**
+     * Forward address search for the address step's search box.
+     *
+     * EXPLICIT SUBMIT ONLY — never call this per keystroke. The server's map
+     * source forbids autocomplete, and the request budget has to be spent on
+     * the query the person actually meant rather than on every prefix of it.
+     */
+    async addressSearch(
+      query: string,
+      country?: string | null,
+    ): Promise<{ results: AddressSearchHit[] }> {
+      const qs = new URLSearchParams({ q: query });
+      if (country) qs.set('country', country);
+      return request<{ results: AddressSearchHit[] }>(`/address/search?${qs.toString()}`);
+    },
+
+    /**
+     * The framed Street View entrance, as an image SOURCE the review card can
+     * hand straight to <Image>.
+     *
+     * The browser key never reaches this SDK (the framed page holds it), so
+     * the picture comes through the server, which does. Returned as a URL plus
+     * the auth header rather than fetched bytes: React Native's Image carries
+     * headers itself, which keeps Blob, FileReader and base64 out of a path
+     * that only has to draw a thumbnail. Mirrors the web SDK's
+     * addressStreetViewPreview, which returns a Blob because a browser <img>
+     * cannot send an Authorization header.
+     */
+    /**
+     * The pinned location as a PICTURE, for the review card.
+     *
+     * A confirmation screen wants a photograph of the place, not a second
+     * instrument: a live map there invites a drag that goes nowhere and
+     * carries the vendor's own controls over the SDK's chrome. Same shape as
+     * the Street View source above, and the same reason for it: the key lives
+     * on the server. lib/authed-image fetches it with the header — an <Image>
+     * given `source.headers` drops them on Android.
+     */
+    staticMapSource(view: {
+      lat: number;
+      lng: number;
+      zoom?: number;
+      width?: number;
+      height?: number;
+    }): { uri: string; headers: Record<string, string> } {
+      const qs = new URLSearchParams({
+        lat: String(view.lat),
+        lng: String(view.lng),
+        zoom: String(view.zoom ?? 16),
+        width: String(Math.round(view.width ?? 640)),
+        height: String(Math.round(view.height ?? 360)),
+      });
+      return { uri: `${base}/address/static-map?${qs.toString()}`, headers };
+    },
+
+    streetViewPreviewSource(frame: {
+      panoId: string;
+      heading: number;
+      pitch: number;
+      fov: number;
+    }): { uri: string; headers: Record<string, string> } {
+      const qs = new URLSearchParams({
+        panoId: frame.panoId,
+        heading: String(frame.heading),
+        pitch: String(frame.pitch),
+        fov: String(frame.fov),
+      });
+      return {
+        uri: `${base}/address/street-view-preview?${qs.toString()}`,
+        headers,
+      };
+    },
+
+    /** The street line for a pin, for the summary card after a locate or a
+     *  drag. Display only — it never decides anything. */
+    async addressReverse(lat: number, lng: number): Promise<AddressReverseResult> {
+      const qs = new URLSearchParams({ lat: String(lat), lng: String(lng) });
+      return request<AddressReverseResult>(`/address/reverse?${qs.toString()}`);
+    },
+
+    /**
+     * Places-backed as-you-type suggestions.
+     *
+     * `session` is ONE token per typing session: it is the billing unit, so
+     * Google bills per session rather than per keystroke. Mint it when the
+     * search screen opens, reuse it for every keystroke, and mint a fresh one
+     * after a details call — that call closes the session.
+     */
+    async addressAutocomplete(
+      query: string,
+      session: string,
+      country?: string | null,
+      near?: { lat: number; lng: number } | null,
+    ): Promise<{ suggestions: PlaceSuggestion[] }> {
+      const qs = new URLSearchParams({ q: query, session });
+      if (country) qs.set('country', country);
+      // The device fix, a RANKING bias so nearby streets come first: without
+      // it "Awolowo Road" in Calabar ranks against every Awolowo Road in the
+      // country. Mirrors the web SDK's api.addressAutocomplete.
+      if (near) {
+        qs.set('lat', String(near.lat));
+        qs.set('lng', String(near.lng));
+      }
+      return request<{ suggestions: PlaceSuggestion[] }>(`/address/autocomplete?${qs.toString()}`);
+    },
+
+    /** Resolve a picked suggestion to coordinates + structured pieces. */
+    async addressPlace(placeId: string, session: string): Promise<{ place: ResolvedPlace }> {
+      const qs = new URLSearchParams({ session });
+      return request<{ place: ResolvedPlace }>(
+        `/address/place/${encodeURIComponent(placeId)}?${qs.toString()}`,
+      );
+    },
+
     async health(): Promise<HealthResponse> {
       // Public endpoint — no auth needed, but the shared headers are harmless.
       return request<HealthResponse>('/health');

package/src/services/deviceMetadata.ts

@@ -15,7 +15,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.4.0';
+export const SDK_VERSION = '2.6.0';
 
 export interface ReactNativeDeviceMetadata {
   sdkType: 'react-native';

package/src/services/errors.ts

@@ -74,8 +74,16 @@ export function mapToKycError(err: unknown, context: ErrorContext): KYCError {
               : err.message || 'This verification feature is currently disabled for your organization.';
       return new KYCError('feature_disabled', message);
     }
-    if (err.statusCode >= 500 || err.statusCode === 0) {
-      // Transient server error that survived retries.
+    // Nothing came back at all — DNS, routing, a refused connection. Kept
+    // SEPARATE from a 5xx: telling somebody the server errored when their
+    // request never arrived sends them looking through server logs for a
+    // request that was never made.
+    if (err.statusCode === 0) {
+      const code: KYCErrorCode = context === 'upload' ? 'upload_failed' : 'network_error';
+      return new KYCError(code, "Couldn't reach the server. Check your connection and try again.");
+    }
+    if (err.statusCode >= 500) {
+      // Transient server error that survived retries — the request DID arrive.
       const code: KYCErrorCode = context === 'upload' ? 'upload_failed' : 'network_error';
       return new KYCError(code, 'A server error occurred. Please try again in a moment.');
     }

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(),
+  };
+}