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

package/src/presence/math.ts

@@ -0,0 +1,44 @@
+// ---------------------------------------------------------------------------
+// Presence math — the pure half of the foreground reporter. On-device
+// evaluation is the contract: the phone decides "inside the fence?" and "what
+// local day/night is it?", and only the derived record (day + flag) ever
+// leaves the device. Raw coordinates never travel after capture.
+//
+// Mirrors the Flutter SDK's presence_math.dart — keep the two in lockstep.
+// ---------------------------------------------------------------------------
+
+const EARTH_RADIUS_M = 6_371_000;
+
+export function haversineMeters(
+  lat1: number,
+  lng1: number,
+  lat2: number,
+  lng2: number,
+): number {
+  const rad = (d: number) => (d * Math.PI) / 180;
+  const dLat = rad(lat2 - lat1);
+  const dLng = rad(lng2 - lng1);
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(rad(lat1)) * Math.cos(rad(lat2)) * Math.sin(dLng / 2) ** 2;
+  return 2 * EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(a)));
+}
+
+/** The server's at-address rule, applied on-device: 250 m, widened to the
+ *  fix's reported accuracy, capped at 1 km. */
+export function insideFence(
+  pin: { lat: number; lng: number },
+  fix: { lat: number; lng: number; accuracy: number | null },
+): boolean {
+  const radius = Math.min(1000, Math.max(250, fix.accuracy ?? 0));
+  return haversineMeters(pin.lat, pin.lng, fix.lat, fix.lng) <= radius;
+}
+
+/** The observation's day + night flag, from the DEVICE's local clock — that is
+ *  the whole point of on-device evaluation. Night = 20:00–05:59 local. */
+export function localDayAndNight(now = new Date()): { day: string; nightPresent: boolean } {
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const day = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+  const hour = now.getHours();
+  return { day, nightPresent: hour >= 20 || hour < 6 };
+}

package/src/presence/post.ts

@@ -0,0 +1,40 @@
+// ---------------------------------------------------------------------------
+// The one wire path for presence observations — shared by the foreground
+// reporter and the background geofence flush, so the two tiers can never
+// drift on the request shape. Best-effort by contract: a failure returns
+// false and the caller keeps its queue.
+// ---------------------------------------------------------------------------
+
+import { resolveBaseUrl } from '../services/resolveUrl';
+
+export interface WireObservation {
+  day: string;
+  source: 'geofence' | 'foreground';
+  dwellMinutes: number;
+  nightPresent: boolean;
+  samples: number;
+  integrity?: { mockLocation?: boolean; emulator?: boolean };
+}
+
+export async function postObservations(
+  apiKey: string,
+  devUrl: string | undefined,
+  externalUserId: string,
+  observations: WireObservation[],
+): Promise<boolean> {
+  if (observations.length === 0) return true;
+  try {
+    const base = resolveBaseUrl(apiKey, devUrl);
+    const response = await fetch(`${base}/api/kyc/address/observations`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({ externalUserId, observations }),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}

package/src/presence/report.ts

@@ -0,0 +1,87 @@
+// ---------------------------------------------------------------------------
+// The FOREGROUND presence reporter — the default tier, no background
+// permission. The host app calls reportAddressPresence() on app open, or the
+// moment the flow submits (watch-wait.ts makes that safe: the watch is minted
+// seconds after the submission is accepted, and a fresh pin waits for it);
+// the SDK takes one while-in-use fix, evaluates the fence ON-DEVICE against
+// the pin stored at capture, and posts a single per-day aggregate. Everything is best-effort: a denied permission, a missing pin, or
+// a network fault returns a reason, never a throw — a presence report must
+// never break the host app's startup path.
+// ---------------------------------------------------------------------------
+
+import * as Location from 'expo-location';
+import { currentPosition } from '../services/location';
+import { insideFence, localDayAndNight } from './math';
+import { postObservations } from './post';
+import { loadPresencePin } from './store';
+import { awaitWatch, fetchWatchStatus, pinIsFresh } from './watch-wait';
+
+export interface ReportPresenceOptions {
+  /** The org's PUBLISHABLE key (the same one the KYC flow mounts with). */
+  apiKey: string;
+  /** The org's user reference — must match the KYC flow's `userId`. */
+  externalUserId: string;
+  /** Dev-server override, exactly like the SDK config's `devUrl`. */
+  devUrl?: string;
+}
+
+export interface ReportPresenceResult {
+  reported: boolean;
+  /** Whether the fix landed inside the fence (null when nothing was reported). */
+  inside: boolean | null;
+  reason:
+    | 'reported'
+    | 'no_pin'
+    | 'services_off'
+    | 'no_fix'
+    | 'outside_fence'
+    /** Nothing is monitoring this user right now, so a report would be dropped. */
+    | 'no_watch'
+    | 'network_error';
+}
+
+export async function reportAddressPresence(
+  options: ReportPresenceOptions,
+): Promise<ReportPresenceResult> {
+  const pin = loadPresencePin(options.externalUserId);
+  if (!pin) return { reported: false, inside: null, reason: 'no_pin' };
+
+  // The phone's location toggle, checked before the permission dance: off,
+  // every fix fails, and `no_fix` told the host nothing about why.
+  const services = await Location.hasServicesEnabledAsync().catch(() => true);
+  if (!services) return { reported: false, inside: null, reason: 'services_off' };
+
+  const fix = await currentPosition();
+  if (!fix) return { reported: false, inside: null, reason: 'no_fix' };
+
+  const inside = insideFence(pin, fix);
+  // An outside fix is NOT evidence of absence (people go to work) — the server
+  // scores presence, never absence — so there is nothing worth sending.
+  if (!inside && fix.mocked !== true) {
+    return { reported: false, inside: false, reason: 'outside_fence' };
+  }
+
+  // The watch is minted seconds after a submission is accepted, and the
+  // ingest drops a report that arrives before it (watch-wait.ts).
+  const watch = await awaitWatch(pinIsFresh(pin), {
+    fetchStatus: () => fetchWatchStatus(options.apiKey, options.devUrl, options.externalUserId),
+  });
+  if (watch === 'absent') return { reported: false, inside, reason: 'no_watch' };
+
+  const { day, nightPresent } = localDayAndNight();
+  // One wire path for both tiers (post.ts) — the request shape cannot fork.
+  const ok = await postObservations(options.apiKey, options.devUrl, options.externalUserId, [
+    {
+      day,
+      source: 'foreground',
+      dwellMinutes: 0,
+      nightPresent,
+      samples: 1,
+      // A mocked fix is REPORTED, flagged — evidence OF fraud is worth
+      // more to the watch than silence.
+      ...(fix.mocked === true ? { integrity: { mockLocation: true } } : {}),
+    },
+  ]);
+  if (!ok) return { reported: false, inside, reason: 'network_error' };
+  return { reported: true, inside, reason: 'reported' };
+}

package/src/presence/sampler.ts

@@ -0,0 +1,110 @@
+// ---------------------------------------------------------------------------
+// Pure state machine for the foreground-service tier. A geofence hands us
+// ENTER/EXIT moments; a periodic location sample hands us POSITIONS, and the
+// job here is to turn positions back into the same enter/exit spans the
+// geofence tier folds, on the SAME stored `enterAt`, so the two tiers
+// cooperate on one state rather than double-counting a stay:
+//
+//   inside,  no open stay  → open one (stamp enterAt)
+//   inside,  open stay     → nothing (the fence or an earlier sample did it)
+//   outside, open stay     → close it: fold the span into per-day aggregates
+//   outside, no open stay  → nothing (absence is never evidence)
+//   mocked                 → report the day FLAGGED, never open a stay
+//
+// Why this exists at all: on phones whose manufacturers kill background work
+// (the Tecno/Infinix/Xiaomi population that dominates our markets), geofence
+// transitions are dropped, silently. A foreground service keeps the process
+// alive and hands it fixes every few minutes; folding those through the same
+// span logic is what makes verification finish on those devices.
+//
+// Mirrors the Flutter plugin's PresenceSampler.kt — keep the two in lockstep.
+// ---------------------------------------------------------------------------
+
+import { foldSpanIntoDays } from './background-math';
+import { insideFence, localDayAndNight } from './math';
+import type { WireObservation } from './post';
+
+export interface SampleFix {
+  lat: number;
+  lng: number;
+  accuracy: number | null;
+  timestamp: number;
+  mocked: boolean | null;
+}
+
+export interface SamplerResult {
+  /** The open stay after these samples (null = none open). */
+  enterAt: number | null;
+  /** Per-day aggregates to queue (same-day entries already merged). */
+  observations: WireObservation[];
+}
+
+/** Merge day aggregates that landed on the same day (several spans a day):
+ *  sum dwell, OR night, sum samples. The geofence flush uses the same rule. */
+export function mergeObservations(
+  existing: WireObservation[],
+  fresh: WireObservation[],
+): WireObservation[] {
+  const byDay = new Map(existing.map((o) => [o.day, { ...o }]));
+  for (const o of fresh) {
+    const prior = byDay.get(o.day);
+    if (!prior) {
+      byDay.set(o.day, { ...o });
+      continue;
+    }
+    prior.dwellMinutes += o.dwellMinutes;
+    prior.nightPresent = prior.nightPresent || o.nightPresent;
+    prior.samples += o.samples;
+    if (o.integrity) prior.integrity = { ...prior.integrity, ...o.integrity };
+  }
+  return [...byDay.values()];
+}
+
+/**
+ * Apply a batch of fixes (any order; sorted here) to the open-stay state.
+ * `offsetMinutes` is the device's UTC offset for the fold; it defaults to the
+ * device's own, and is a parameter only so the maths is testable in any TZ.
+ */
+export function applyLocationSamples(
+  pin: { lat: number; lng: number },
+  samples: ReadonlyArray<SampleFix>,
+  enterAt: number | null,
+  offsetMinutes?: number,
+): SamplerResult {
+  let open = enterAt;
+  let observations: WireObservation[] = [];
+  const ordered = [...samples]
+    .filter((s) => Number.isFinite(s.timestamp))
+    .sort((a, b) => a.timestamp - b.timestamp);
+
+  for (const fix of ordered) {
+    if (fix.mocked === true) {
+      const { day, nightPresent } = localDayAndNight(new Date(fix.timestamp));
+      observations = mergeObservations(observations, [
+        {
+          day,
+          source: 'geofence',
+          dwellMinutes: 0,
+          nightPresent,
+          samples: 1,
+          integrity: { mockLocation: true },
+        },
+      ]);
+      continue;
+    }
+    const inside = insideFence(pin, fix);
+    if (inside) {
+      if (open == null) open = fix.timestamp;
+      continue;
+    }
+    if (open == null) continue;
+    const days = foldSpanIntoDays(open, fix.timestamp, offsetMinutes);
+    open = null;
+    if (days.length === 0) continue;
+    observations = mergeObservations(
+      observations,
+      days.map((d) => ({ ...d, source: 'geofence' as const, samples: 1 })),
+    );
+  }
+  return { enterAt: open, observations };
+}

package/src/presence/status.ts

@@ -0,0 +1,92 @@
+// ---------------------------------------------------------------------------
+// Tier visibility + recovery. A revoked permission silently downgrades the
+// presence tier, and "silently" is the defect: the host app cannot ask the
+// person to restore what it does not know is gone. presenceStatus() answers
+// "which tier is actually running for this user?", and openLocationSettings()
+// is the only honest recovery path — neither OS allows re-prompting in-app
+// after a denial, so the road back runs through Settings.
+//
+// The phone's LOCATION SERVICES toggle is checked as well as the permissions.
+// Permission granted with the toggle off produced `no_fix` on every report
+// and nothing said why; OkHi's integration guidance calls this out for the
+// same reason. It is a first-class input to the tier (tier.ts).
+// ---------------------------------------------------------------------------
+
+import { Linking, Platform } from 'react-native';
+import * as Location from 'expo-location';
+import { foregroundServiceRunning } from './foreground-service';
+import { geofenceArmed } from './geofence';
+import { loadPresencePin } from './store';
+import { resolvePresenceTier, type PermissionState, type PresenceTier } from './tier';
+
+export type { PresenceTier } from './tier';
+
+export interface PresenceStatus {
+  /** The tier that is ACTUALLY running, not the one that was asked for. */
+  tier: PresenceTier;
+  /** Whether a pin is stored for this user (without one, no tier can run). */
+  pinStored: boolean;
+  /** Whether the stored pin is the always-on arrangement. */
+  alwaysOn: boolean;
+  /** The phone's location services switch. Off, nothing can run whatever
+   *  the permissions say; `openLocationSettings('services')` is the road back. */
+  locationServicesEnabled: boolean;
+  foregroundPermission: PermissionState;
+  backgroundPermission: PermissionState;
+  /** The geofence is registered with the OS right now. */
+  geofenceArmed: boolean;
+  /** The Android foreground service is running right now (always false on iOS). */
+  foregroundServiceRunning: boolean;
+}
+
+function normalise(status: string | undefined): PermissionState {
+  if (status === 'granted') return 'granted';
+  if (status === 'denied') return 'denied';
+  return 'undetermined';
+}
+
+export async function presenceStatus(externalUserId: string): Promise<PresenceStatus> {
+  const pin = loadPresencePin(externalUserId);
+  const [fg, bg, armed, services, service] = await Promise.all([
+    Location.getForegroundPermissionsAsync().catch(() => null),
+    Location.getBackgroundPermissionsAsync().catch(() => null),
+    geofenceArmed(),
+    // An unanswerable check reads as ON: the permissions below still gate,
+    // and a false "off" would send people to Settings for nothing.
+    Location.hasServicesEnabledAsync().catch(() => true),
+    foregroundServiceRunning(),
+  ]);
+  const inputs = {
+    pinStored: pin != null,
+    locationServicesEnabled: services,
+    foregroundPermission: normalise(fg?.status),
+    backgroundPermission: normalise(bg?.status),
+    geofenceArmed: armed,
+    foregroundServiceRunning: service,
+  };
+  return {
+    tier: resolvePresenceTier(inputs),
+    alwaysOn: pin?.alwaysOn === true,
+    ...inputs,
+  };
+}
+
+/**
+ * Deep-link to Settings — the only road back after a denial or a switched-off
+ * toggle. `'app'` (default) opens the app's own settings page (permissions);
+ * `'services'` opens the phone's location-services screen on Android, which
+ * is where the toggle lives (iOS has no such deep link, so it falls back to
+ * the app page). Never throws; a host may call it straight from a button.
+ */
+export async function openLocationSettings(target: 'app' | 'services' = 'app'): Promise<void> {
+  try {
+    if (target === 'services' && Platform.OS === 'android') {
+      await Linking.sendIntent('android.settings.LOCATION_SOURCE_SETTINGS');
+      return;
+    }
+    await Linking.openSettings();
+  } catch {
+    // Nothing to do: the OS refused, and the host's copy already told the
+    // person where to go by hand.
+  }
+}

package/src/presence/store.ts

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// The on-device pin store. When a workflow enables presence verification, the
+// captured pin is saved LOCALLY (keyed by the org's user reference) so later
+// app opens can evaluate "am I at the address?" without the coordinates ever
+// leaving the phone. A small JSON file in the app's document directory via
+// expo-file-system — loaded through the SDK's optional-module pattern, so a
+// host app without the module simply has no presence tier (never a crash).
+// ---------------------------------------------------------------------------
+
+import { readJsonFile, writeJsonFile } from './fs';
+
+export interface StoredPin {
+  lat: number;
+  lng: number;
+  savedAt: string;
+  /** Always-on monitoring: the pin lives as long as the arrangement does
+   *  (cleared only by clearPresencePin — revoke or sign-out), because the
+   *  server keeps renewing the watch and reports must keep flowing. */
+  alwaysOn?: boolean;
+}
+
+const FILE_NAME = 'myaza-kyc-presence.json';
+
+/**
+ * How long a stored pin may drive reports. The watch it feeds resolves within
+ * its policy window (30 days at the longest) and the server discards reports
+ * for a resolved watch anyway — but the DEVICE kept sampling location on
+ * every app open forever, for a check that had finished. The server cannot
+ * say "stop" without breaking the ingest endpoint's enumeration safety (an
+ * unknown user and a resolved watch must answer identically), so the bound
+ * lives here: longest window plus resolution slack, then the pin self-expires
+ * and the reporter goes quiet before ever touching the GPS.
+ */
+export const PIN_TTL_DAYS = 45;
+
+export function pinExpired(pin: StoredPin, nowMs: number = Date.now()): boolean {
+  // An always-on pin has no end date by design (the OkHi model): monitoring
+  // continues until revoked, and the TTL below exists only for BOUNDED
+  // watches whose purpose has a deadline.
+  if (pin.alwaysOn === true) return false;
+  const saved = Date.parse(pin.savedAt);
+  // An unparseable stamp is treated as expired: both platforms have always
+  // written savedAt, so a missing one is corruption, and corrupt entries must
+  // age out rather than report forever.
+  if (Number.isNaN(saved)) return true;
+  // Strictly past the TTL — the Flutter mirror compares the same way.
+  return nowMs - saved > PIN_TTL_DAYS * 24 * 60 * 60 * 1000;
+}
+
+function readAll(): Record<string, StoredPin> {
+  return readJsonFile(FILE_NAME) as Record<string, StoredPin>;
+}
+
+function writeAll(pins: Record<string, StoredPin>): void {
+  writeJsonFile(FILE_NAME, pins as Record<string, unknown>);
+}
+
+/** Saves the captured pin for later foreground reports. Never throws. */
+export function savePresencePin(
+  externalUserId: string,
+  pin: { lat: number; lng: number },
+  opts?: { alwaysOn?: boolean },
+): void {
+  if (!externalUserId) return;
+  const pins = readAll();
+  pins[externalUserId] = {
+    lat: pin.lat,
+    lng: pin.lng,
+    savedAt: new Date().toISOString(),
+    ...(opts?.alwaysOn === true ? { alwaysOn: true } : {}),
+  };
+  writeAll(pins);
+}
+
+/** The stored pin for a user, or null (no store / never captured here /
+ *  aged out — an expired pin is cleared on the way through). */
+export function loadPresencePin(externalUserId: string): StoredPin | null {
+  const pin = readAll()[externalUserId];
+  if (!pin || typeof pin.lat !== 'number' || typeof pin.lng !== 'number') return null;
+  if (pinExpired(pin)) {
+    clearPresencePin(externalUserId);
+    return null;
+  }
+  return pin;
+}
+
+/** Drops a stored pin (e.g. after a watch resolves or the user signs out). */
+export function clearPresencePin(externalUserId: string): void {
+  const pins = readAll();
+  if (externalUserId in pins) {
+    delete pins[externalUserId];
+    writeAll(pins);
+  }
+}

package/src/presence/tier.ts

@@ -0,0 +1,36 @@
+// ---------------------------------------------------------------------------
+// Which presence tier is ACTUALLY running, as one pure decision — so the
+// answer presenceStatus() gives can be pinned without a device, and so the
+// Flutter mirror (presence_tier.dart) can be held to the same table.
+//
+// The location-services toggle sits ABOVE every permission: with services
+// off, a granted permission and an armed fence produce no fix and no
+// transition, so nothing is running whatever the grants say. That was the
+// silent case — permission granted, toggle off, `no_fix` forever — and it is
+// why the switch is a first-class input here rather than folded into one of
+// the permission states.
+// ---------------------------------------------------------------------------
+
+export type PresenceTier = 'background' | 'foreground' | 'none';
+
+export type PermissionState = 'granted' | 'denied' | 'undetermined';
+
+export interface TierInputs {
+  pinStored: boolean;
+  locationServicesEnabled: boolean;
+  foregroundPermission: PermissionState;
+  backgroundPermission: PermissionState;
+  /** The OS geofence is registered right now. */
+  geofenceArmed: boolean;
+  /** The Android foreground service is running right now. */
+  foregroundServiceRunning: boolean;
+}
+
+export function resolvePresenceTier(i: TierInputs): PresenceTier {
+  if (!i.pinStored || !i.locationServicesEnabled) return 'none';
+  if (i.backgroundPermission === 'granted' && (i.geofenceArmed || i.foregroundServiceRunning)) {
+    return 'background';
+  }
+  if (i.foregroundPermission === 'granted') return 'foreground';
+  return 'none';
+}

package/src/presence/watch-wait.ts

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// Waiting for the watch. The server mints an AddressWatch in the post-terminal
+// hook chain, seconds AFTER a submission is accepted, and its ingest is
+// enumeration-safe by contract: an observation for a user with no live watch
+// answers `accepted: 0` exactly as an unknown user would, and is dropped. So
+// a report made the moment onSubmit fires — the natural place for a host to
+// make one — landed on nothing (iPhone + S24, 2026-09-07: three watches in a
+// row lapsed INCONCLUSIVE with zero observations while both phones sat at the
+// pin). The reporter therefore asks where the watch stands before it posts,
+// and when the pin was captured minutes ago it WAITS for the watch to appear,
+// bounded, rather than posting into the gap. Mirrors the Flutter SDK's
+// presence_watch_wait.dart — keep the two in lockstep.
+// ---------------------------------------------------------------------------
+
+import { resolveBaseUrl } from '../services/resolveUrl';
+
+/** A pin saved this recently was captured by a flow whose watch may still be minting. */
+export const FRESH_PIN_MS = 15 * 60 * 1000;
+/** How long a submit-time report waits for its watch before giving up. */
+export const WATCH_WAIT_MS = 90 * 1000;
+export const WATCH_POLL_MS = 3 * 1000;
+
+export type WatchPresence = 'live' | 'absent' | 'unknown';
+
+export function pinIsFresh(pin: { savedAt: string }, nowMs: number = Date.now()): boolean {
+  const saved = Date.parse(pin.savedAt);
+  return !Number.isNaN(saved) && nowMs - saved <= FRESH_PIN_MS;
+}
+
+/** The server's public status for the user's watch, or null when it could not be read. */
+export async function fetchWatchStatus(
+  apiKey: string,
+  devUrl: string | undefined,
+  externalUserId: string,
+): Promise<string | null> {
+  try {
+    const base = resolveBaseUrl(apiKey, devUrl);
+    const response = await fetch(
+      `${base}/api/kyc/address/presence/${encodeURIComponent(externalUserId)}`,
+      { headers: { Authorization: `Bearer ${apiKey}` } },
+    );
+    if (!response.ok) return null;
+    const body = (await response.json()) as { status?: unknown };
+    return typeof body.status === 'string' ? body.status : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface AwaitWatchDeps {
+  fetchStatus: () => Promise<string | null>;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  waitMs?: number;
+  pollMs?: number;
+}
+
+const realSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Whether a live watch exists to receive a report. Only `in_progress` is
+ * live: a resolved cycle, or none at all, drops what is posted. An
+ * unreadable status is `unknown`, and the post goes ahead — a network doubt
+ * must not silence a report the server might accept. A FRESH pin changes the
+ * rule: its watch is probably still being minted (or the previous cycle has
+ * just lapsed and the new one is about to replace it), so the status is
+ * re-read until it turns live or the wait runs out.
+ */
+export async function awaitWatch(fresh: boolean, deps: AwaitWatchDeps): Promise<WatchPresence> {
+  const sleep = deps.sleep ?? realSleep;
+  const now = deps.now ?? Date.now;
+  const deadline = now() + (deps.waitMs ?? WATCH_WAIT_MS);
+  const pollMs = deps.pollMs ?? WATCH_POLL_MS;
+  for (;;) {
+    const status = await deps.fetchStatus();
+    if (status === 'in_progress') return 'live';
+    if (!fresh) return status === null ? 'unknown' : 'absent';
+    if (now() >= deadline) return status === null ? 'unknown' : 'absent';
+    await sleep(pollMs);
+  }
+}