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

package/src/config/keyPeopleSections.ts

@@ -0,0 +1,167 @@
+import type { KeyPersonEntry } from './keyPeople';
+import type { KeyPersonRole } from '../types/business';
+
+/**
+ * The sectioned key-people model: UBOs / Shareholders / Directors &
+ * representatives as VIEWS over one shared list of people.
+ *
+ * A section is not a bucket. One human is a director AND a 30% owner, and the
+ * register files them that way, so an entry appears in every section whose
+ * definition it meets — membership is derived from the roles it holds and the
+ * stake it declares, never stored. Quick-add grants an existing person another
+ * hat instead of retyping them; classification by ownership happens here
+ * exactly as the server escalates it, so the screen never disagrees with what
+ * the submission will be read as.
+ */
+
+export type KeyPeopleSection = 'ubos' | 'shareholders' | 'representatives';
+
+/** Strongest first — the headline role on one-role surfaces. Mirrors the
+ *  server's precedence in `key-people/roles.ts`; keep the two in lockstep. */
+const ROLE_PRECEDENCE: KeyPersonRole[] = [
+  'beneficial_owner',
+  'director',
+  'signatory',
+  'shareholder',
+];
+
+export function primaryRole(roles: KeyPersonRole[]): KeyPersonRole {
+  for (const role of ROLE_PRECEDENCE) if (roles.includes(role)) return role;
+  return 'shareholder';
+}
+
+/** The roles an entry actually holds; falls back to the headline for rows
+ *  minted before `roles` existed (restored sessions). */
+export function rolesOf(entry: Pick<KeyPersonEntry, 'role' | 'roles'>): KeyPersonRole[] {
+  return entry.roles && entry.roles.length > 0 ? entry.roles : [entry.role];
+}
+
+/** The declared stake as a number, or null when blank/unparseable. */
+export function stakeOf(entry: Pick<KeyPersonEntry, 'ownershipPct'>): number | null {
+  const raw = entry.ownershipPct.trim();
+  if (raw === '') return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Which sections this entry belongs to.
+ *
+ * - UBOs: a natural person holding the beneficial-owner role OR a stake at or
+ *   above the threshold — the same escalation the server performs, so a
+ *   shareholder who types 60% moves up on screen exactly as they will in the
+ *   submission. A company never qualifies (a beneficial owner is a natural
+ *   person in every regime that defines one).
+ * - Shareholders: every corporate holder (whatever its stake — the never-a-UBO
+ *   rule made visible), plus people with a declared holding or shareholder
+ *   role below the threshold. A person the UBO section claimed is not ALSO a
+ *   plain shareholder: same stake, one classification.
+ * - Representatives: anyone holding director or signatory.
+ */
+export function sectionsFor(
+  entry: KeyPersonEntry,
+  threshold: number,
+): Set<KeyPeopleSection> {
+  const roles = rolesOf(entry);
+  const stake = stakeOf(entry);
+  const out = new Set<KeyPeopleSection>();
+
+  const isUbo =
+    !entry.isCorporate &&
+    (roles.includes('beneficial_owner') || (stake != null && stake >= threshold));
+  if (isUbo) out.add('ubos');
+  if (
+    entry.isCorporate ||
+    (!isUbo && (roles.includes('shareholder') || (stake != null && stake > 0)))
+  ) {
+    out.add('shareholders');
+  }
+  if (roles.includes('director') || roles.includes('signatory')) {
+    out.add('representatives');
+  }
+  return out;
+}
+
+/** Indices of the entries each section shows, in list order. */
+export function sectionMembers(
+  rows: KeyPersonEntry[],
+  threshold: number,
+): Record<KeyPeopleSection, number[]> {
+  const out: Record<KeyPeopleSection, number[]> = {
+    ubos: [],
+    shareholders: [],
+    representatives: [],
+  };
+  rows.forEach((row, index) => {
+    for (const section of sectionsFor(row, threshold)) out[section].push(index);
+  });
+  return out;
+}
+
+/** The role a section's add-tile (and quick-add chip) grants. */
+export const SECTION_ROLE: Record<KeyPeopleSection, KeyPersonRole> = {
+  ubos: 'beneficial_owner',
+  shareholders: 'shareholder',
+  representatives: 'director',
+};
+
+/**
+ * Entries offerable as quick-add chips for a section: already entered, named,
+ * not yet a member, and eligible (a company can never be quick-added as a
+ * UBO). One tap grants the section's role — the Didit chip, minus its
+ * duplicate-name bug.
+ */
+export function quickAddCandidates(
+  rows: KeyPersonEntry[],
+  section: KeyPeopleSection,
+  threshold: number,
+): number[] {
+  const members = new Set(sectionMembers(rows, threshold)[section]);
+  return rows
+    .map((row, index) => ({ row, index }))
+    .filter(({ row, index }) => {
+      if (members.has(index)) return false;
+      if (row.name.trim().length < 2) return false;
+      if (section === 'ubos' && row.isCorporate) return false;
+      // Only offer a chip that would DO something. Membership is derived, so
+      // granting a role does not always produce it: a beneficial owner is not
+      // also a plain shareholder (same stake, one classification), so offering
+      // them under Shareholders gave a chip that could be tapped forever and
+      // never move anybody. An affordance that does nothing is worse than an
+      // absent one, because the applicant concludes the app is broken.
+      return sectionsFor(grantRole(row, section), threshold).has(section);
+    })
+    .map(({ index }) => index);
+}
+
+/** Grant an entry another hat (quick-add). The headline follows precedence. */
+export function grantRole(entry: KeyPersonEntry, section: KeyPeopleSection): KeyPersonEntry {
+  const roles = rolesOf(entry);
+  const granted = SECTION_ROLE[section];
+  const next = roles.includes(granted) ? roles : [...roles, granted];
+  return { ...entry, roles: next, role: primaryRole(next) };
+}
+
+/**
+ * Take an entry out of a section (the card's X). Removing the section's roles
+ * is enough when membership came from them; when it came from a declared
+ * stake (or nothing else keeps the row alive) the honest reading of "remove
+ * from UBOs" is "remove this person" — the caller deletes the row when this
+ * returns null.
+ */
+export function withoutSection(
+  entry: KeyPersonEntry,
+  section: KeyPeopleSection,
+  threshold: number,
+): KeyPersonEntry | null {
+  const dropped: KeyPersonRole[] =
+    section === 'representatives' ? ['director', 'signatory'] : [SECTION_ROLE[section]];
+  const remaining = rolesOf(entry).filter((r) => !dropped.includes(r));
+  if (remaining.length === 0) return null;
+  const next = { ...entry, roles: remaining, role: primaryRole(remaining) };
+  // Still a member by stake? Then role removal did not remove them, and the
+  // tap meant more than that.
+  if (sectionsFor(next, threshold).has(section)) return null;
+  return next;
+}
+

package/src/config/registrationHint.ts

@@ -70,7 +70,7 @@ export function registrationNumberHint(
       tip: NG_TIP,
       isValidFormat: (value) => NG_PREFIX_RE.test(value.trim()),
       formatError:
-        'Start with RC, BN, IT, LP or LLP followed by the number — no spaces, e.g. RC0000000.',
+        'Start with RC, BN, IT, LP or LLP followed by the number, no spaces, e.g. RC0000000.',
     };
   }
 

package/src/config/stepOrder.ts

@@ -11,8 +11,8 @@
 //               capture → (nfc) → (liveness) → (poa) → (questionnaire) →
 //               submitted
 //   business:   consent → (email) → (phone) → business-details →
-//               (key-people) → (documents) → (applicant-role → capture leg) →
-//               (questionnaire) → submitted
+//               (documents) → (questionnaire) → (key-people) →
+//               (applicant-role → country-select → capture leg) → submitted
 //
 // Mirrors the web SDK's `lib/step-order.ts`, plus the `nfc` step, which is a
 // real step here — the web SDK can't do ISO-DEP so it only previews the screen.
@@ -20,6 +20,7 @@
 
 import type { WorkflowBusinessConfig } from '../types/business';
 import type { KYCStep } from '../types/config';
+import { applyResubmitSteps, type ResubmitConfig } from '../lib/resubmit';
 import { businessSectionSteps, hasApplicantVerification } from './businessSteps';
 
 export interface StepOrderOptions {
@@ -34,6 +35,14 @@ export interface StepOrderOptions {
   hasPhoneVerification: boolean;
   hasPoa: boolean;
   hasQuestionnaire: boolean;
+  /**
+   * A reviewer sent this back to redo specific steps.
+   *
+   * Applied LAST, over the fully-built order, so it narrows whatever the flow
+   * would otherwise have been rather than having to know how that order was
+   * assembled — which differs between the individual and KYB branches below.
+   */
+  resubmit?: ResubmitConfig | null;
 }
 
 // Contact-verification OTP steps sit right after consent (both flows) — a cheap
@@ -56,10 +65,22 @@ function captureLeg(o: StepOrderOptions): KYCStep[] {
 }
 
 export function buildStepOrder(o: StepOrderOptions): KYCStep[] {
+  return applyResubmitSteps(fullStepOrder(o), o.resubmit);
+}
+
+/** The flow as configured, before any reviewer narrowing. */
+function fullStepOrder(o: StepOrderOptions): KYCStep[] {
   // Business (KYB) flow — the application section, then (when the workflow
   // requires applicant verification) the ordinary individual capture leg.
   if (o.isBusiness) {
-    const steps: KYCStep[] = ['consent', ...contactSteps(o), ...businessSectionSteps(o.business)];
+    // The questionnaire sits INSIDE the business section (before key people) —
+    // its questions are about the company, so it stays with the company form
+    // rather than trailing the applicant's own capture leg.
+    const steps: KYCStep[] = [
+      'consent',
+      ...contactSteps(o),
+      ...businessSectionSteps(o.business, o.hasQuestionnaire),
+    ];
     if (hasApplicantVerification(o.business)) {
       // The applicant may hold an ID issued anywhere the org can verify —
       // more than one granted country (hasCountrySelect, derived from the
@@ -68,7 +89,6 @@ export function buildStepOrder(o: StepOrderOptions): KYCStep[] {
       if (o.hasCountrySelect) steps.push('country-select');
       steps.push('id-type', ...captureLeg(o));
     }
-    if (o.hasQuestionnaire) steps.push('questionnaire');
     steps.push('submitted');
     return steps;
   }

package/src/config/theme.ts

@@ -37,7 +37,13 @@ export const LIGHT_COLORS: MyazaColorScheme = {
   backgroundSecondary: '#F6F5FE',
   textDark: '#070330',
   textSecondary: '#5A5775',
-  textMuted: '#828197',
+  // React's muted-foreground, exactly. The mobile SDKs had invented a THIRD,
+  // dimmer text tier that web does not have, and it failed WCAG AA in both
+  // modes: 3.79:1 on white and 2.97:1 on the default dark, dropping to 2.45:1
+  // on the dark backgrounds orgs actually brand with. Nothing is gained by a
+  // tier nobody can read, so it takes the same value as the tier above it, the
+  // way web does with one token for both.
+  textMuted: '#5A5775',
   border: '#D3CFFC',
   primary: '#5645F5',
   onPrimary: '#FFFFFF',
@@ -61,7 +67,7 @@ export const DARK_COLORS: MyazaColorScheme = {
   backgroundSecondary: '#0F0C2E',
   textDark: '#F6F5FE',
   textSecondary: '#ACABBA',
-  textMuted: '#5A5775',
+  textMuted: '#ACABBA',
   border: '#302D53',
   primary: '#7B6EF7',
   onPrimary: '#FFFFFF',

package/src/config/website.ts

@@ -0,0 +1,36 @@
+// Is this a website address?
+//
+// Deliberately not a URL parser. `new URL(value)` rejects "company.com" for
+// having no scheme, which is how almost everyone writes a website, and accepts
+// "mailto:x@y" and "javascript:alert(1)" for having one. Both answers are the
+// wrong way round for a field labelled "Website". Mirrors the web SDK's
+// lib/website.ts — keep the two in lockstep.
+
+/** Trim, drop a scheme, drop a trailing slash. What the checks below run on. */
+function hostOf(value: string): string {
+  return value
+    .trim()
+    .replace(/^https?:\/\//i, '')
+    .replace(/\/.*$/, '')
+    .replace(/:\d+$/, '');
+}
+
+const HOST = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i;
+
+export function isValidWebsite(value: string): boolean {
+  const raw = value.trim();
+  if (raw === '') return true; // Empty is for the required-field check, not this.
+
+  // A scheme we do not serve is a mistake worth catching: "mailto:" in a
+  // website box is a different thing entirely, not a typo in this one.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(raw) && !/^https?:\/\//i.test(raw)) return false;
+
+  const host = hostOf(raw);
+  if (host.length === 0 || host.length > 253) return false;
+  if (!HOST.test(host)) return false;
+
+  // A TLD of at least two letters. Rules out "company." and "192.168.0.1",
+  // neither of which is a website somebody meant to type.
+  const tld = host.slice(host.lastIndexOf('.') + 1);
+  return /^[a-z]{2,}$/i.test(tld);
+}

package/src/config/workflowMerge.ts

@@ -20,6 +20,7 @@ export const WORKFLOW_KEYS = [
   'country',
   'countries',
   'idTypes',
+  'multiId',
   'enableSelfie',
   'enableDocumentCapture',
   'allowDocumentUpload',
@@ -27,6 +28,7 @@ export const WORKFLOW_KEYS = [
   'livenessMode',
   'flashSequenceLength',
   'deviceIntelligence',
+  'keyPeopleLinkRecovery',
   'requireMobileDevice',
   'voiceGuidance',
   'showThemeToggle',
@@ -40,6 +42,8 @@ export const WORKFLOW_KEYS = [
   'questionnaire',
   'proofOfAddress',
   'nfc',
+  // Set only on a session a reviewer sent back, never on a published flow.
+  'resubmit',
 ] as const;
 
 export type WorkflowKey = (typeof WORKFLOW_KEYS)[number];
@@ -96,6 +100,7 @@ const APPLICANT_LEG_KEYS = [
   'country',
   'countries',
   'idTypes',
+  'multiId',
   'enableSelfie',
   'enableDocumentCapture',
   'allowDocumentUpload',

package/src/emrtd/activeAuth.ts

@@ -0,0 +1,100 @@
+import { toBase64 } from './bytes';
+import { EF, type Transceive } from './files';
+import { readOptionalFile } from './optionalRead';
+import type { SecureMessagingSession } from './secureMessaging';
+
+// ---------------------------------------------------------------------------
+// ACTIVE AUTHENTICATION — asking the chip to prove it is not a copy.
+//
+// Passive authentication (the SOD) proves the data was signed by the issuing
+// state. It cannot prove this is the chip they signed it onto: copy a genuine
+// passport's files onto a blank chip and every hash and signature still
+// verifies, because none of them is bound to the silicon.
+//
+// So we ask the chip to SIGN something. Its private key never leaves it, and
+// the matching public key sits in DG15 — which is itself hashed into the SOD,
+// so the issuing state has vouched for it. A cloner can copy DG15; they cannot
+// copy the key that answers for it.
+//
+// TWO THINGS MATTER HERE, and neither is visible from this file alone:
+//
+//   • THE CHALLENGE IS THE SERVER'S. We do not generate it. A nonce we chose
+//     would let anyone replay one captured (challenge, signature) pair forever,
+//     which is the clone this is meant to catch.
+//   • WE DO NOT VERIFY. The signature is carried to the server untouched and
+//     checked there against a SOD-bound DG15. A client that verified its own
+//     chip would be a client an attacker can simply patch — the same reason
+//     passive authentication has always run server-side.
+//
+// Both are also why this file is short: reading and forwarding is the whole job.
+// ---------------------------------------------------------------------------
+
+/** ICAO 9303-11 fixes the Active-Authentication challenge at 8 bytes. */
+export const AA_CHALLENGE_BYTES = 8;
+
+/** The server's challenge: its id (to spend) and its bytes (for the chip). */
+export interface AaChallenge {
+  id: string;
+  bytes: Uint8Array;
+}
+
+export interface ActiveAuthRead {
+  /** Base64 DG15 — the chip's AA public key. Absent ⇒ the chip has no AA. */
+  dg15?: string;
+  /** Base64 signature over the challenge. Absent ⇒ the chip would not sign. */
+  signature?: string;
+}
+
+/**
+ * INTERNAL AUTHENTICATE — hand the chip the challenge, take back its signature.
+ *
+ * Le is 0 (meaning "as much as you have"): the answer is one RSA modulus or one
+ * raw r||s pair, and the length varies by document. Naming a length would work
+ * on the passports we happened to test and truncate the rest.
+ */
+async function internalAuthenticate(
+  sm: SecureMessagingSession,
+  transceive: Transceive,
+  challenge: Uint8Array,
+): Promise<Uint8Array | null> {
+  try {
+    const { data, statusWord } = sm.unprotect(
+      await transceive(
+        sm.protect({ cla: 0x00, ins: 0x88, p1: 0x00, p2: 0x00, data: challenge, le: 0 }),
+      ),
+    );
+    if (statusWord !== 0x9000 || data.length === 0) return null;
+    return data;
+  } catch {
+    // A chip that carries DG15 but refuses to sign is unusual but not a
+    // finding: it costs the anti-clone check, never the read.
+    return null;
+  }
+}
+
+/**
+ * Read DG15 and get the chip to sign the server's challenge.
+ *
+ * Best-effort throughout, like every optional group: most chips in the field
+ * support no Active Authentication at all, and reporting that as a problem
+ * would flag the majority of genuine passports.
+ */
+export async function readActiveAuth(
+  sm: SecureMessagingSession,
+  transceive: Transceive,
+  challenge: AaChallenge | undefined,
+): Promise<ActiveAuthRead> {
+  // No challenge means the server could not issue one. Reading DG15 anyway
+  // would cost a round trip on the document for a key nothing can be checked
+  // against, so the whole step is skipped.
+  if (!challenge || challenge.bytes.length !== AA_CHALLENGE_BYTES) return {};
+
+  const dg15 = await readOptionalFile(sm, transceive, EF.DG15, 'DG15');
+  if (!dg15) return {};
+
+  const signature = await internalAuthenticate(sm, transceive, challenge.bytes);
+  return {
+    dg15: toBase64(dg15),
+    ...(signature ? { signature: toBase64(signature) } : {}),
+  };
+}

package/src/emrtd/extras.ts

@@ -0,0 +1,76 @@
+import { findTlv, readTlv } from './der';
+import { EF, type Transceive } from './files';
+import { readOptionalFile } from './optionalRead';
+import type { SecureMessagingSession } from './secureMessaging';
+
+// ---------------------------------------------------------------------------
+// The optional detail groups: DG7 (displayed signature image), DG11
+// (additional personal details), DG12 (additional document details).
+//
+// All three are BAC-readable like DG1/DG2, small (a few KB between them), and
+// OPTIONAL BY STANDARD — many issuers simply do not write them. So the read is
+// gated on EF.COM, the chip's own table of contents: one tiny file names
+// exactly which data groups exist, and absent groups are skipped instead of
+// being probed with SELECTs the chip will refuse. When COM itself cannot be
+// read (or does not parse), every group is attempted best-effort — the worst
+// case is a fast refusal per absent file, which readOptionalFile absorbs.
+//
+// Deliberately read LAST, after the portrait: they are nice-to-have context,
+// and a session that drops while fetching them has already banked everything
+// that matters. Like DG2 they are only read once the SOD arrived — the server
+// authenticates each group against it, and an unverifiable extra is one an
+// attacker could have substituted.
+//
+// (DG3/DG4 — fingerprints and iris — are NOT here and never will be: they sit
+// behind Extended Access Control, decryptable only by government inspection
+// systems holding terminal-authentication certificates.)
+// ---------------------------------------------------------------------------
+
+/** LDS1 data-group tag byte → DG number (ICAO 9303-10). */
+const TAG_TO_DG: Readonly<Record<number, number>> = {
+  0x61: 1, 0x75: 2, 0x63: 3, 0x76: 4, 0x65: 5, 0x66: 6, 0x67: 7, 0x68: 8,
+  0x69: 9, 0x6a: 10, 0x6b: 11, 0x6c: 12, 0x6d: 13, 0x6e: 14, 0x6f: 15, 0x70: 16,
+};
+
+/**
+ * Parse EF.COM's data-group presence list (tag 5C inside the outer 60).
+ * Null when the bytes do not parse as a COM — the caller then probes instead.
+ */
+export function parseComDataGroups(com: Uint8Array): Set<number> | null {
+  const outer = readTlv(com);
+  if (!outer || outer.tag !== 0x60) return null;
+  const list = findTlv(outer.value, 0x5c);
+  if (!list) return null;
+  const present = new Set<number>();
+  for (const byte of list.value) {
+    const dg = TAG_TO_DG[byte];
+    if (dg !== undefined) present.add(dg);
+  }
+  return present;
+}
+
+export interface ExtraGroupReads {
+  dg7: Uint8Array | null;
+  dg11: Uint8Array | null;
+  dg12: Uint8Array | null;
+}
+
+/**
+ * Read whichever of DG7/DG11/DG12 the chip declares (or, without a readable
+ * COM, whichever answer). Every read is best-effort — a failure costs the
+ * group, never the session's banked result.
+ */
+export async function readExtraGroups(
+  sm: SecureMessagingSession,
+  transceive: Transceive,
+): Promise<ExtraGroupReads> {
+  const com = await readOptionalFile(sm, transceive, EF.COM, 'EF.COM');
+  const declared = com ? parseComDataGroups(com) : null;
+  const want = (dg: number): boolean => declared === null || declared.has(dg);
+
+  return {
+    dg7: want(7) ? await readOptionalFile(sm, transceive, EF.DG7, 'DG7') : null,
+    dg11: want(11) ? await readOptionalFile(sm, transceive, EF.DG11, 'DG11') : null,
+    dg12: want(12) ? await readOptionalFile(sm, transceive, EF.DG12, 'DG12') : null,
+  };
+}

package/src/emrtd/files.ts

@@ -26,6 +26,11 @@ export const EF = {
   COM: 0x011e,
   DG1: 0x0101,
   DG2: 0x0102,
+  DG7: 0x0107,
+  DG11: 0x010b,
+  DG12: 0x010c,
+  /** DG15 — the Active-Authentication public key (see activeAuth.ts). */
+  DG15: 0x010f,
   SOD: 0x011d,
 } as const;
 

package/src/emrtd/index.ts

@@ -29,3 +29,4 @@ export {
 export { parseDg1 } from './dg1';
 export { decodeChipImage, isNfcAvailable, nfcUnavailableReason } from './native';
 export { cancelChipRead, readPassportChip, type ChipReadOptions } from './read';
+export { AA_CHALLENGE_BYTES, readActiveAuth, type AaChallenge, type ActiveAuthRead } from './activeAuth';

package/src/emrtd/read.ts

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

package/src/emrtd/session.ts

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