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

package/src/lib/multi-id.ts

@@ -0,0 +1,210 @@
+// Multi-ID flows on React Native. A PORT of the web SDK's lib/multi-id.ts,
+// kept byte-for-byte in its logic: the server validates the pick sequence the
+// client produced, so a client that computes options differently produces
+// submissions the server rejects. If you change a rule here, change it in
+// kyc-sdk-react/src/lib/multi-id.ts, kyc-core/src/lib/multi-id.ts and the
+// dashboard's required-ids-model.ts in the same commit.
+//
+// Multi-ID flows: a workflow's `multiId` block asks for SEVERAL ID checks in
+// one run — the applicant picks each slot's ID from what the admin allowed for
+// THEIR country (a picked ID disappears from later slots), ONE selfie covers
+// the whole run, and everything submits as ONE verification the server judges
+// by the pass policy.
+//
+// Multi-region works: the country-select step comes first as usual, and the
+// run then walks THAT country's slots (`countries[].multiIdSlots`). The pure
+// helpers here MIRROR the server's lib/multi-id.ts exactly — the safe-options
+// rule is what keeps an applicant from ever being offered a pick that would
+// strand a later slot, and the server validates the same sequence.
+
+export interface MultiIdConfig {
+  count: number;
+  minPassed: number;
+}
+
+export interface MultiIdCountry {
+  country: string;
+  idTypes?: string[];
+  /** This country's per-verification ID allowlists. */
+  multiIdSlots?: Array<{ idTypes?: string[] }>;
+}
+
+interface MultiIdSourceConfig {
+  multiId?: MultiIdConfig;
+  subjectType?: string;
+  /** The EFFECTIVE country (post country-select) — whose slots the run walks. */
+  country?: string;
+  countries?: MultiIdCountry[];
+  idTypes?: string[];
+}
+
+/** The workflow's multiId POLICY — null for ordinary flows and every KYB flow. */
+export function multiIdConfigFrom(config: MultiIdSourceConfig): MultiIdConfig | null {
+  if (config.subjectType === 'business') return null;
+  const block = config.multiId;
+  if (!block || typeof block.count !== 'number') return null;
+  const count = Math.trunc(block.count);
+  // REJECT an out-of-range count rather than clamping it. The server returns
+  // null here, so clamping made the client walk 3 checks for a config the
+  // server does not consider multi-ID at all — and clamping `minPassed`
+  // against the RAW count could ask for 9 of 3 to pass, which nothing can
+  // satisfy. Same rule, both sides, or the client builds submissions the
+  // server rejects.
+  if (!Number.isInteger(count) || count < 2 || count > 3) return null;
+  return {
+    count,
+    minPassed:
+      typeof block.minPassed === 'number' && Number.isInteger(block.minPassed)
+        ? Math.min(Math.max(block.minPassed, 1), count)
+        : count,
+  };
+}
+
+/** The country entry the run walks: the EFFECTIVE country's, else the legacy
+ *  single-country shape. */
+export function multiIdCountryEntry(config: MultiIdSourceConfig): MultiIdCountry | null {
+  const country = config.country;
+  if (config.countries && config.countries.length > 0) {
+    return config.countries.find((c) => c.country === country) ?? null;
+  }
+  return country ? { country, idTypes: config.idTypes } : null;
+}
+
+/**
+ * The ID types the picked country offers: its pinned list, else everything the
+ * server granted there.
+ */
+export function multiIdOfferedTypes(
+  config: MultiIdSourceConfig,
+  serverIdTypes: Array<{ country: string; idType: string }>,
+): string[] {
+  const entry = multiIdCountryEntry(config);
+  if (!entry) return [];
+  if (entry.idTypes && entry.idTypes.length > 0) return entry.idTypes;
+  return serverIdTypes.filter((row) => row.country === entry.country).map((row) => row.idType);
+}
+
+/** Per-slot option lists (a pinned slot keeps its list; others offer everything). */
+export function multiIdSlotOptions(
+  count: number,
+  slots: Array<{ idTypes?: string[] }> | undefined,
+  offered: string[],
+): string[][] {
+  const offeredSet = new Set(offered);
+  return Array.from({ length: count }, (_, i) => {
+    const pinned = slots?.[i]?.idTypes;
+    const base = pinned && pinned.length > 0 ? pinned : offered;
+    return base.filter((t) => offeredSet.has(t));
+  });
+}
+
+/** The first reachable dead-end across pick orders, or null. */
+export function multiIdFirstDeadEnd(
+  slotOptions: string[][],
+): { picks: string[]; slotIndex: number } | null {
+  const walk = (index: number, picked: string[]): { picks: string[]; slotIndex: number } | null => {
+    if (index >= slotOptions.length) return null;
+    const available = slotOptions[index]!.filter((t) => !picked.includes(t));
+    if (available.length === 0) return { picks: picked, slotIndex: index };
+    for (const pick of available) {
+      const deadEnd = walk(index + 1, [...picked, pick]);
+      if (deadEnd) return deadEnd;
+    }
+    return null;
+  };
+  return walk(0, []);
+}
+
+/** The picks a slot may SAFELY offer: unused AND non-stranding. */
+export function multiIdSafeOptions(
+  slotOptions: string[][],
+  slotIndex: number,
+  picked: string[],
+): string[] {
+  const remaining = slotOptions.slice(slotIndex + 1);
+  return (slotOptions[slotIndex] ?? [])
+    .filter((t) => !picked.includes(t))
+    .filter(
+      (t) =>
+        multiIdFirstDeadEnd(
+          remaining.map((opts) => opts.filter((o) => o !== t && !picked.includes(o))),
+        ) === null,
+    );
+}
+
+export interface MultiIdPlan {
+  count: number;
+  minPassed: number;
+  /** Which slot is being walked (clamped; equals count once every slot committed). */
+  index: number;
+  /** The current slot is the final one. */
+  last: boolean;
+  /** ID types committed so far, in order. */
+  picked: string[];
+  /** What the CURRENT slot's picker may offer. */
+  safeOptions: string[];
+}
+
+/** The active plan, or null for ordinary flows. */
+export function multiIdPlan(
+  config: MultiIdSourceConfig,
+  state: { multiIdSlotIndex: number; multiIdSlots: Array<{ idType: string }> },
+  serverIdTypes: Array<{ country: string; idType: string }>,
+): MultiIdPlan | null {
+  const cfg = multiIdConfigFrom(config);
+  if (!cfg) return null;
+  const offered = multiIdOfferedTypes(config, serverIdTypes);
+  const options = multiIdSlotOptions(cfg.count, multiIdCountryEntry(config)?.multiIdSlots, offered);
+  const picked = state.multiIdSlots.map((s) => s.idType);
+  const index = Math.min(Math.max(state.multiIdSlotIndex, 0), cfg.count);
+  return {
+    count: cfg.count,
+    minPassed: cfg.minPassed,
+    index,
+    last: index >= cfg.count - 1,
+    picked,
+    safeOptions: index < cfg.count ? multiIdSafeOptions(options, index, picked) : [],
+  };
+}
+
+/** Which evidence step one slot's ID opens on. */
+export function multiIdEvidenceStep(
+  def: { requiresDocumentCapture: boolean } | null | undefined,
+): 'id-input' | 'document-capture' {
+  return def && def.requiresDocumentCapture === false ? 'id-input' : 'document-capture';
+}
+
+/**
+ * The committed slots as the WIRE sees them — an explicit whitelist, because
+ * the slots also carry local preview images for the back journey and those must
+ * never reach the submission or the session-progress blob. Whitelist, not
+ * spread: a field added to the slot later cannot leak by default.
+ */
+export function multiIdWireSlots(
+  slots: Array<{
+    idType: string;
+    idNumber?: string;
+    documentFront?: string;
+    documentBack?: string;
+    documentFrontVideo?: string;
+    documentBackVideo?: string;
+  }>,
+): Array<{
+  idType: string;
+  idNumber?: string;
+  documentFront?: string;
+  documentBack?: string;
+  documentFrontVideo?: string;
+  documentBackVideo?: string;
+}> {
+  // The chip is attached by the caller after this whitelist (it is a payload,
+  // not a mediaId), so it is absent here and not stripped.
+  return slots.map((s) => ({
+    idType: s.idType,
+    ...(s.idNumber ? { idNumber: s.idNumber } : {}),
+    ...(s.documentFront ? { documentFront: s.documentFront } : {}),
+    ...(s.documentBack ? { documentBack: s.documentBack } : {}),
+    ...(s.documentFrontVideo ? { documentFrontVideo: s.documentFrontVideo } : {}),
+    ...(s.documentBackVideo ? { documentBackVideo: s.documentBackVideo } : {}),
+  }));
+}

package/src/lib/poa-country-gate.ts

@@ -0,0 +1,27 @@
+// ---------------------------------------------------------------------------
+// The Proof of Address step's country gate.
+//
+// On the ADDRESS scope the declared country is the applicant's own claim about
+// their market: it picks the document kinds on offer, the PoA vendor market and
+// rides the submission as the verification's country, and the scope seeds none
+// (see AddressCountryControl). A document uploaded with no country behind it is
+// not yet a complete answer, so Continue holds until one is declared (user
+// decision 2026-09-08). Elsewhere the flow's own country stands and the gate
+// never bites; an org that accepts exactly ONE country has the control show it
+// as a settled fact, which counts as declared.
+//
+// A THREE-WAY MIRROR of the web SDK's lib/poa-country-gate.ts and Flutter's
+// config/poa_country_gate.dart; change the rule in one and change all three.
+// ---------------------------------------------------------------------------
+
+/** Whether the Proof of Address step may continue as far as the COUNTRY is
+ *  concerned (the upload has its own gate). */
+export function poaCountryDeclared(facts: {
+  scope: string | null;
+  selectedCountry: string | null | undefined;
+  offered: readonly string[];
+}): boolean {
+  if (facts.scope !== 'address') return true;
+  if (facts.selectedCountry?.trim()) return true;
+  return facts.offered.length === 1;
+}

package/src/lib/resubmit.ts

@@ -0,0 +1,130 @@
+// Narrowing a flow to the steps a reviewer asked the applicant to redo.
+//
+// A reviewer looked at a finished verification and sent it back — usually
+// because one thing was unreadable, not because everything was wrong. Making
+// somebody retake a passport photo is reasonable; making them redo consent, the
+// ID picker, liveness and a questionnaire to fix that photo is how you lose them.
+//
+// The instruction rides the session's config snapshot (`config.resubmit`), which
+// is how every other per-session flow instruction travels. An SDK that predates
+// this simply does not read the key and runs the whole flow, which is the safe
+// degradation: asking for too much is recoverable, silently skipping a step the
+// reviewer wanted is not.
+import type { KYCStep } from '../types/config';
+
+export interface ResubmitConfig {
+  /** Steps to redo, in flow order. Never empty — the server omits the key instead. */
+  steps: string[];
+  /** Reviewer's note to the applicant. */
+  message?: string | null;
+}
+
+/**
+ * Steps that are always kept, whatever the reviewer ticked.
+ *
+ * `consent` because a flow with no first screen is disorienting, and it is where
+ * the redo is explained. `submitted` because a flow has to end somewhere.
+ * Neither is something the applicant is being asked to redo — they are the
+ * frame around what is.
+ */
+const ALWAYS: KYCStep[] = ['consent', 'submitted'];
+
+/**
+ * One ID's evidence — a FAMILY, not alternatives a reviewer picks between.
+ *
+ * Which member a flow contains depends on the ID type: a number-only ID has
+ * `id-input`, a document ID has `document-capture` (and maybe `nfc`). At the
+ * moment the order is built nobody has chosen one yet, so the flow is shaped by
+ * a default. A plan naming `id-input` against an order still shaped for
+ * `document-capture` therefore matched NOTHING, fell through to the safety net
+ * below, and silently ran the entire flow — which is exactly the bug a reviewer
+ * sees as "I asked for the ID and it made them do everything again".
+ *
+ * Asking for one member asks for whichever this flow turns out to have.
+ */
+const EVIDENCE: KYCStep[] = ['id-input', 'document-capture', 'nfc'];
+
+/**
+ * Steps a narrowed flow keeps regardless, because without them it cannot
+ * produce a submission at all.
+ *
+ * A resubmission is a NEW verification on a FRESH session: nothing is carried
+ * forward from the one being redone, so the applicant must still say which ID
+ * this is and supply it. `POST /verify` requires an `idType`, and a number-only
+ * ID requires the number with it.
+ *
+ * So narrowing removes the things arranged AROUND the identity — liveness,
+ * proof of address, the questionnaire, contact checks — and never the identity
+ * itself. The alternative is a two-screen flow that collects a photo and then
+ * fails to submit, which is worse for the applicant than being asked for one
+ * extra screen.
+ */
+const INDIVIDUAL_REQUIRED: KYCStep[] = ['id-type', ...EVIDENCE];
+const BUSINESS_REQUIRED: KYCStep[] = ['business-details'];
+
+/**
+ * Narrow a full step order to the redo, preserving flow order.
+ *
+ * Order comes from `order`, never from the reviewer's list: they ticked
+ * checkboxes, and walking somebody through liveness before document capture
+ * because that is the order the boxes were ticked in would be nonsense.
+ *
+ * Returns the ORIGINAL order untouched when the instruction is absent, empty, or
+ * matches nothing we know. That last case matters: a server that learns a new
+ * step name before this SDK does must not produce a two-screen flow that
+ * collects nothing.
+ */
+export function applyResubmitSteps(
+  order: KYCStep[],
+  resubmit: ResubmitConfig | undefined | null,
+): KYCStep[] {
+  const asked = resubmit?.steps;
+  if (!asked?.length) return order;
+
+  const wantsEvidence = asked.some((step) => EVIDENCE.includes(step as KYCStep));
+
+  // Does the instruction name anything this flow actually has? If not, it came
+  // from a server that knows a step name this SDK does not — and narrowing on it
+  // would quietly drop whatever was really asked for. Checked BEFORE the
+  // required steps are added, or those alone would make every unknown plan look
+  // recognised and turn the safety net below into dead code.
+  const recognised = wantsEvidence || asked.some((step) => order.includes(step as KYCStep));
+  if (!recognised) return order;
+
+  const wanted = new Set<string>(asked);
+  if (wantsEvidence) for (const step of EVIDENCE) wanted.add(step);
+  for (const step of order.includes('business-details') ? BUSINESS_REQUIRED : INDIVIDUAL_REQUIRED) {
+    wanted.add(step);
+  }
+
+  const narrowed = order.filter((step) => wanted.has(step) || ALWAYS.includes(step));
+
+  // Nothing but the frame survived, so the instruction named steps this flow
+  // does not contain. Run everything rather than nothing.
+  const collects = narrowed.some((step) => !ALWAYS.includes(step));
+  return collects ? narrowed : order;
+}
+
+/** Whether this mount is a targeted redo, for the wording on screen. */
+export function isResubmission(resubmit: ResubmitConfig | undefined | null): boolean {
+  return Boolean(resubmit?.steps?.length);
+}
+
+/**
+ * The reviewer's note to the applicant, when this mount is a targeted redo.
+ *
+ * The dashboard's send-back dialog asks a reviewer to explain the problem — its
+ * placeholder is literally "Your document photo was too dark to read, please
+ * retake it in good light." The server stamps that note onto the session and
+ * every SDK parses it into config, and until now NONE of them displayed it. So
+ * a send-back reached the applicant as a flow that had silently lost most of
+ * its steps, with nothing saying why they were back or what to do differently.
+ *
+ * Returns null when there is nothing to show, so a caller can render this
+ * unconditionally.
+ */
+export function resubmitNote(resubmit: ResubmitConfig | undefined | null): string | null {
+  if (!isResubmission(resubmit)) return null;
+  const note = resubmit?.message?.trim();
+  return note && note.length > 0 ? note : null;
+}

package/src/lib/result-copy.ts

@@ -0,0 +1,116 @@
+import type { VerificationOutcome } from './result-wait';
+import type { BiometricCopyText } from '../config/biometricOptions';
+
+// ─── What the terminal screens say ──────────────────────────────────────────
+//
+// Pure so it is testable without React. The server's own reason wins on a
+// decline or an error when it sent one: it is written for the applicant.
+// UK English, no em dashes (user-facing copy rule).
+
+export type ResultTone = 'success' | 'error' | 'info';
+
+export interface ResultCopy {
+  tone: ResultTone;
+  title: string;
+  description: string;
+}
+
+export interface WaitingCopy {
+  title: string;
+  description: string;
+}
+
+/**
+ * The ONE loading screen after the capture. On a re-authentication that waits
+ * for its verdict it spans the selfie upload, the submission and the poll, so
+ * it names the check rather than any of the three steps behind it. A retry in
+ * flight replaces the description, never the title: the person is still
+ * waiting for the same thing. `override` is the org's own words for the
+ * screen (lib/biometric-copy.ts), field by field over the default.
+ */
+export function describeWaiting(opts: {
+  scope: string | null;
+  waitsForResult: boolean;
+  retry?: { attempt: number; total: number } | null;
+  override?: BiometricCopyText | null;
+}): WaitingCopy {
+  const base = withOverride(waitingCopyFor(opts.scope, opts.waitsForResult), opts.override);
+  if (opts.retry) {
+    return { title: base.title, description: `Connection issue, retrying (${opts.retry.attempt}/${opts.retry.total}).` };
+  }
+  return base;
+}
+
+function waitingCopyFor(scope: string | null, waitsForResult: boolean): WaitingCopy {
+  if (scope === 'biometric-authentication') {
+    return waitsForResult
+      ? { title: "Checking it's you", description: 'Matching your selfie against the photo on record. This usually takes a few seconds.' }
+      : { title: 'Sending your face check', description: 'This only takes a moment.' };
+  }
+  if (scope === 'biometric-enrollment') {
+    return { title: 'Saving your selfie', description: 'It becomes the reference for your future face checks.' };
+  }
+  return { title: 'Submitting your verification', description: 'Please wait a moment.' };
+}
+
+/** The org's own words for a screen, over the default, field by field. */
+function withOverride<T extends { title: string; description: string }>(base: T, override?: BiometricCopyText | null): T {
+  if (!override) return base;
+  return {
+    ...base,
+    ...(override.title ? { title: override.title } : {}),
+    ...(override.description ? { description: override.description } : {}),
+  };
+}
+
+/** What the person is told, per outcome. The server's own reason wins on a
+ *  decline or an error when it sent one; it is written for the applicant.
+ *  `copy` is the org's own words for the two verdict screens: on a decline
+ *  its description wins even over the server's reason, since the org chose
+ *  to say that. */
+export function describeOutcome(
+  outcome: VerificationOutcome,
+  copy?: { verified?: BiometricCopyText | null; declined?: BiometricCopyText | null },
+): ResultCopy {
+  if (outcome.kind === 'timeout') {
+    return {
+      tone: 'info',
+      title: 'Still checking',
+      description: "This is taking longer than usual. You'll be notified as soon as it's done.",
+    };
+  }
+  switch (outcome.status) {
+    case 'approved':
+      return withOverride(
+        { tone: 'success', title: "You're verified", description: 'Your face matched the photo on record.' },
+        copy?.verified,
+      );
+    case 'declined':
+      return withOverride(
+        {
+          tone: 'error',
+          title: "We couldn't confirm it's you",
+          description: outcome.reason ?? "Your face didn't match the photo on record.",
+        },
+        copy?.declined,
+      );
+    case 'in_review':
+      return {
+        tone: 'info',
+        title: 'Under review',
+        description: "A reviewer will take a look. You'll be notified of the outcome.",
+      };
+    case 'error':
+      return {
+        tone: 'error',
+        title: 'Something went wrong',
+        description: outcome.reason ?? "We couldn't complete your check. Please try again in a moment.",
+      };
+    default:
+      return {
+        tone: 'info',
+        title: 'Check submitted',
+        description: "You'll be notified of the result.",
+      };
+  }
+}

package/src/lib/result-wait.ts

@@ -0,0 +1,53 @@
+import type { SessionStatus, VerificationStatusResponse } from '../services/api-types';
+
+// ─── Waiting for a verdict in the flow ──────────────────────────────────────
+//
+// The platform is fire-and-forget: /verify answers in milliseconds and the
+// worker settles the check afterwards. A re-authentication is the one flow
+// whose verdict the person is waiting for RIGHT THERE, so the submitted step
+// polls the publishable status endpoint (state + reason, never result data)
+// until the check leaves its pending states. Pure and injectable, like the
+// presence watch wait: the screen owns nothing but the rendering.
+
+export const RESULT_WAIT_MS = 60 * 1000;
+export const RESULT_POLL_MS = 1500;
+
+/** The states a submitted check passes through before it settles. */
+const PENDING: ReadonlySet<SessionStatus> = new Set(['not_started', 'in_progress', 'processing']);
+
+export type VerificationOutcome =
+  | { kind: 'settled'; status: SessionStatus; reason: string | null; reasonCode: string | null }
+  | { kind: 'timeout' };
+
+export interface AwaitOutcomeDeps {
+  /** One status read; null on any failure (the wait keeps going). */
+  fetchStatus: () => Promise<VerificationStatusResponse | null>;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  waitMs?: number;
+  pollMs?: number;
+}
+
+export function isPendingStatus(status: SessionStatus): boolean {
+  return PENDING.has(status);
+}
+
+/**
+ * Poll until the check settles or the budget runs out. A failed read is not
+ * a verdict: it is skipped and the next poll tries again, so a network blip
+ * mid-wait never reads as an outcome.
+ */
+export async function awaitVerificationOutcome(deps: AwaitOutcomeDeps): Promise<VerificationOutcome> {
+  const sleep = deps.sleep ?? ((ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const now = deps.now ?? Date.now;
+  const deadline = now() + (deps.waitMs ?? RESULT_WAIT_MS);
+  const pollMs = deps.pollMs ?? RESULT_POLL_MS;
+  for (;;) {
+    const read = await deps.fetchStatus();
+    if (read && !isPendingStatus(read.status)) {
+      return { kind: 'settled', status: read.status, reason: read.reason ?? null, reasonCode: read.reasonCode ?? null };
+    }
+    if (now() >= deadline) return { kind: 'timeout' };
+    await sleep(pollMs);
+  }
+}

package/src/lib/review-map-surface.ts

@@ -0,0 +1,26 @@
+// The review card's map falls back in the SAME order on every SDK: the picture
+// (the Maps Static API through the server), then the framed Google map the pin
+// step drew, then the built-in tiles. Pure, so a test can pin the order — the
+// Flutter card skipped the middle rung and confirmed the address on
+// OpenStreetMap where RN confirmed it on Google (user report 2026-09-08).
+// Mirrors kyc-sdk-flutter's reviewMapSurface; keep the two in lockstep.
+
+export type ReviewMapSurface = 'stub' | 'picture' | 'pending' | 'framed' | 'builtIn';
+
+export function reviewMapSurface(facts: {
+  vendorsStubbed: boolean;
+  /** The picture's bytes have landed. */
+  hasStaticMap: boolean;
+  /** The picture was refused (a project without the Static API 404s). */
+  staticMapFailed: boolean;
+  /** A server-minted maps frame URL this install can render. */
+  hasFrame: boolean;
+}): ReviewMapSurface {
+  if (facts.vendorsStubbed) return 'stub';
+  if (facts.hasStaticMap) return 'picture';
+  // Nothing to draw yet and no verdict either: hold the picture's space rather
+  // than flashing the live map for the half second before the bytes land.
+  if (!facts.staticMapFailed) return 'pending';
+  if (facts.hasFrame) return 'framed';
+  return 'builtIn';
+}

package/src/lib/scope.ts

@@ -0,0 +1,31 @@
+// Workflow SCOPE — what a flow verifies about the subject (mirror of the
+// server's lib/workflows/scope.ts and the web SDK's lib/scope.ts; keep the
+// three in lockstep). Absent = the full verification.
+
+export type WorkflowScope =
+  | 'address'
+  | 'biometric-authentication'
+  | 'biometric-enrollment'
+  | 'questionnaire'
+  | 'contact';
+
+/** The marker idType a scoped submission carries (the KYB product-in-idType
+ *  convention — the server requires the matching published workflow). */
+export const SCOPE_ID_TYPES: Record<WorkflowScope, string> = {
+  address: 'address',
+  'biometric-authentication': 'biometric-auth',
+  'biometric-enrollment': 'biometric-enroll',
+  questionnaire: 'questionnaire',
+  contact: 'contact',
+};
+
+export function configScope(config: { scope?: WorkflowScope | string }): WorkflowScope | null {
+  const value = config.scope;
+  return value && value in SCOPE_ID_TYPES ? (value as WorkflowScope) : null;
+}
+
+/** The biometric scopes run the liveness capture; every other scope has no
+ *  camera step at all. */
+export function isFaceScope(scope: WorkflowScope | null): boolean {
+  return scope === 'biometric-authentication' || scope === 'biometric-enrollment';
+}

package/src/lib/screen-corners.ts

@@ -0,0 +1,50 @@
+import { Dimensions, Platform } from 'react-native';
+import { initialWindowMetrics } from 'react-native-safe-area-context';
+
+// Apple's grammar for nested corners is CONCENTRIC: an inset card's radius is
+// the DISPLAY's corner radius minus the gap between card and screen edge —
+// that is why the system share sheet's curve runs parallel to the phone's.
+// No public API exposes the display radius, so iOS resolves it from the
+// model's logical screen size (the per-device values Apple ships, from
+// UIScreen's private _displayCornerRadius, in points). Unknown hardware falls
+// back on whether the display is rounded at all: home-indicator devices are,
+// square-corner devices are not.
+
+/** `short x long` logical points → display corner radius in points. */
+const IOS_RADII: Record<string, number> = {
+  // X / XS / 11 Pro are 39 on the same canvas as the 12–13 mini's 44; the
+  // minis are the ones still in pockets, so the shared key takes their value.
+  '375x812': 44,
+  '414x896': 41.5, // XR / 11 / XS Max / 11 Pro Max
+  '390x844': 47.33, // 12 / 12 Pro / 13 / 13 Pro / 14
+  '428x926': 53.33, // 12–13 Pro Max / 14 Plus
+  '393x852': 55, // 14 Pro / 15 / 15 Pro / 16 / 16e
+  '430x932': 55, // 14 Pro Max / 15 Plus / 15 Pro Max / 16 Plus
+  '402x874': 62, // 16 Pro
+  '440x956': 62, // 16 Pro Max
+};
+
+/**
+ * The display's own corner radius, in points/dp. 0 means a square-cornered
+ * screen (or one we cannot judge), and the caller picks its flat-world look.
+ */
+export function displayCornerRadius(): number {
+  const { width, height } = Dimensions.get('screen');
+  const key = `${Math.round(Math.min(width, height))}x${Math.round(Math.max(width, height))}`;
+  const bottomInset = initialWindowMetrics?.insets?.bottom ?? 0;
+
+  if (Platform.OS === 'ios') {
+    const known = IOS_RADII[key];
+    if (known != null) return known;
+    // Unlisted model: a home indicator means a rounded display; 47 is the
+    // middle of the modern range.
+    return bottomInset > 0 ? 47 : 0;
+  }
+
+  // Android has no cheap signal (the RoundedCorner API needs native code).
+  // A small bottom inset is gesture navigation — overwhelmingly the modern,
+  // rounded-display phones — while ~48dp is the opaque 3-button bar, which
+  // says nothing. Modest on purpose: an under-estimate still looks composed,
+  // an over-estimate looks like a mistake.
+  return bottomInset > 0 && bottomInset <= 32 ? 32 : 0;
+}