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

package/src/config/proofOfAddress.ts

@@ -8,12 +8,13 @@
 // server is going to make anyway.
 // ---------------------------------------------------------------------------
 
-import type { PoaDocumentType, ProofOfAddressConfig } from '../types/workflow';
+import type { PoaDocumentType, PoaNameRule, ProofOfAddressConfig } from '../types/workflow';
 
 export const POA_TYPE_LABELS: Record<PoaDocumentType, string> = {
   utility_bill: 'Utility bill',
   bank_statement: 'Bank statement',
   tenancy_agreement: 'Tenancy agreement',
+  government_document: 'Government-issued document',
   other: 'Other document',
 };
 
@@ -21,9 +22,15 @@ const ALL_POA_TYPES: PoaDocumentType[] = [
   'utility_bill',
   'bank_statement',
   'tenancy_agreement',
+  'government_document',
   'other',
 ];
 
+/** A kind THIS build can label and draw. A newer kind the dashboard offers
+ *  before the SDK ships is hidden rather than rendered as a blank row. */
+const knownKinds = (kinds: readonly string[] | undefined): PoaDocumentType[] =>
+  (kinds ?? []).filter((k): k is PoaDocumentType => (ALL_POA_TYPES as string[]).includes(k));
+
 /** Default recency window the server checks the document date against. */
 export const DEFAULT_POA_MAX_AGE_DAYS = 90;
 
@@ -32,10 +39,52 @@ export function hasProofOfAddressStep(poa: ProofOfAddressConfig | undefined | nu
   return poa?.enabled === true;
 }
 
-/** The document kinds on offer. An absent or empty list means all of them. */
-export function poaDocumentTypes(poa: ProofOfAddressConfig | undefined): PoaDocumentType[] {
-  const configured = poa?.documentTypes;
-  return configured && configured.length > 0 ? configured : ALL_POA_TYPES;
+/**
+ * The document kinds on offer for `country` (mirror of the web SDK's
+ * `poaOfferedKinds` — keep the three in lockstep): that country's override
+ * when the workflow declares one, else the global list, else all four.
+ */
+export function poaDocumentTypes(
+  poa: ProofOfAddressConfig | undefined,
+  country?: string | null,
+): PoaDocumentType[] {
+  const override = knownKinds(country ? poa?.countryDocuments?.[country.toUpperCase()] : undefined);
+  if (override.length > 0) return override;
+  const configured = knownKinds(poa?.documentTypes);
+  return configured.length > 0 ? configured : ALL_POA_TYPES;
+}
+
+/**
+ * The name rule the server judges THIS document under — the country's per-kind
+ * exception, else the workflow default, else `required`. Mirror of the web
+ * SDK's `poaNamePolicy` and the server's `resolvePoaNamePolicy` — keep in
+ * lockstep. Read only to word the step: under `off` the header stops asking
+ * for the applicant's name.
+ */
+export function poaNamePolicy(
+  poa: ProofOfAddressConfig | undefined | null,
+  country: string | undefined | null,
+  kind: PoaDocumentType | undefined | null,
+): PoaNameRule {
+  const exception = country && kind ? poa?.countryNameMatch?.[country.toUpperCase()]?.[kind] : undefined;
+  if (exception === 'required' || exception === 'optional' || exception === 'off') return exception;
+  const def = poa?.nameMatch;
+  return def === 'optional' || def === 'off' ? def : 'required';
+}
+
+/**
+ * Whether the org's accepted-country list admits `country`. An empty list
+ * accepts everyone; an unknown country is not refused here (the server is the
+ * gate, and it is soft on full flows).
+ */
+export function poaCountryAccepted(
+  poa: ProofOfAddressConfig | undefined | null,
+  country: string | undefined | null,
+): boolean {
+  const accepted = poa?.countries;
+  if (!accepted?.length || !country) return true;
+  const code = country.toUpperCase();
+  return accepted.some((c) => c.toUpperCase() === code);
 }
 
 /**
@@ -63,12 +112,6 @@ export const POA_ACCEPTED_MIME_TYPES = [
   'application/pdf',
 ] as const;
 
-/**
- * Local size cap, matching the web SDK. The server allows more, but rejecting
- * here gives an immediate, specific message instead of a slow 413.
- */
-export const POA_MAX_BYTES = 20 * 1024 * 1024;
-
 export function isAcceptedPoaMimeType(mimeType: string | undefined): boolean {
   const base = (mimeType?.split(';')[0] ?? '').trim().toLowerCase();
   return (POA_ACCEPTED_MIME_TYPES as readonly string[]).includes(base);

package/src/config/regions.ts

@@ -116,3 +116,27 @@ export function groupCountriesByRegion(codes: string[]): RegionGroup[] {
     countries: buckets.get(region)!.sort((a, b) => a.name.localeCompare(b.name)),
   }));
 }
+
+/**
+ * Lift the visitor's IP country out of its alphabetical or regional place to
+ * the top of a picker, so the one country most likely to be theirs is the
+ * first thing they see rather than something to scroll for.
+ *
+ * Takes the ALREADY-FILTERED list: the pin stays subject to the search, so
+ * typing narrows to what was asked for rather than keeping a row that does
+ * not match it. Generic over the row shape because the country-select step
+ * pins bare ISO codes and the dial-code sheet pins option objects; one rule,
+ * two callers. Mirrors the web SDK's CountryRegionPicker + PhoneNumberInput
+ * and Flutter's `pinGeoRow`.
+ */
+export function pinGeoRow<T>(
+  visible: readonly T[],
+  geoCountry: string | null | undefined,
+  codeOf: (item: T) => string,
+): { pinned: T | null; rest: T[] } {
+  const geo = geoCountry?.trim().toUpperCase();
+  if (!geo) return { pinned: null, rest: [...visible] };
+  const hit = visible.find((item) => codeOf(item).toUpperCase() === geo);
+  if (hit === undefined) return { pinned: null, rest: [...visible] };
+  return { pinned: hit, rest: visible.filter((item) => item !== hit) };
+}

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,20 +20,47 @@
 
 import type { WorkflowBusinessConfig } from '../types/business';
 import type { KYCStep } from '../types/config';
+import { applyResubmitSteps, type ResubmitConfig } from '../lib/resubmit';
+import { addressFlowSteps, type AddressFlowOptions } from '../lib/address-flow';
 import { businessSectionSteps, hasApplicantVerification } from './businessSteps';
 
 export interface StepOrderOptions {
   isBusiness: boolean;
+  /** Scoped flows: no identity section — each scope's headline step is the
+   *  flow (see lib/scope.ts). */
+  scope?: import('../lib/scope').WorkflowScope | null;
   /** Business (KYB) configuration — drives the application-section steps. */
   business?: WorkflowBusinessConfig;
   hasDocCapture: boolean;
   hasNfc: boolean;
   hasLiveness: boolean;
   hasCountrySelect: boolean;
+  /**
+   * Whether the flow opens on the consent screen. Absent = yes. `false` is the
+   * workflow's `consentStep: false`: the host app has already asked, so the
+   * flow opens on its first real step instead (config/consentStep.ts).
+   */
+  hasConsent?: boolean;
   hasEmailVerification: boolean;
   hasPhoneVerification: boolean;
   hasPoa: boolean;
+  hasAddressCollection: boolean;
+  /**
+   * Which address screens the flow has, from the ONE `addressFlowFor` call.
+   * The list is built by `addressFlowSteps`, the same builder the address
+   * steps navigate by, so the progress bar and the flow cannot disagree.
+   * Absent falls back to the default shape (no search, entrance offered).
+   */
+  addressFlow?: AddressFlowOptions;
   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 +83,27 @@ function captureLeg(o: StepOrderOptions): KYCStep[] {
 }
 
 export function buildStepOrder(o: StepOrderOptions): KYCStep[] {
+  return applyResubmitSteps(fullStepOrder(o), o.resubmit);
+}
+
+/** The flow's opening screen: consent, unless the workflow switched it off. */
+function openingSteps(o: StepOrderOptions): KYCStep[] {
+  return o.hasConsent === false ? [] : ['consent'];
+}
+
+/** 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[] = [
+      ...openingSteps(o),
+      ...contactSteps(o),
+      ...businessSectionSteps(o.business, o.hasQuestionnaire, o.hasAddressCollection),
+    ];
     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,16 +112,56 @@ export function buildStepOrder(o: StepOrderOptions): KYCStep[] {
       if (o.hasCountrySelect) steps.push('country-select');
       steps.push('id-type', ...captureLeg(o));
     }
+    steps.push('submitted');
+    return steps;
+  }
+
+  // Scoped flows: the scope's headline section IS the flow.
+  if (o.scope === 'address') {
+    const steps: KYCStep[] = [...openingSteps(o), ...contactSteps(o)];
+    if (o.hasPoa) steps.push('proof-of-address');
+    steps.push(
+      ...addressFlowSteps(
+        o.addressFlow ?? { searchAvailable: false, photoMode: 'optional', streetViewOffered: false },
+      ),
+    );
+    if (o.hasQuestionnaire) steps.push('questionnaire');
+    steps.push('submitted');
+    return steps;
+  }
+  if (o.scope === 'biometric-authentication' || o.scope === 'biometric-enrollment') {
+    const steps: KYCStep[] = [...openingSteps(o), ...contactSteps(o), 'liveness'];
     if (o.hasQuestionnaire) steps.push('questionnaire');
     steps.push('submitted');
     return steps;
   }
+  if (o.scope === 'questionnaire') {
+    return [...openingSteps(o), ...contactSteps(o), 'questionnaire', 'submitted'];
+  }
+  if (o.scope === 'contact') {
+    return [...openingSteps(o), ...contactSteps(o), 'submitted'];
+  }
 
   const middle: KYCStep[] = [...captureLeg(o)];
   if (o.hasPoa) middle.push('proof-of-address');
+  // The address flow is FOUR real steps on an individual flow (find it, confirm
+  // it, show it, commit it), so the progress bar advances through them and back
+  // is ordinary step navigation. KYB keeps the single premises step, inserted
+  // by businessSectionSteps above.
+  if (o.hasAddressCollection) {
+    middle.push(
+      ...addressFlowSteps(
+        o.addressFlow ?? {
+          searchAvailable: false,
+          photoMode: 'optional',
+          streetViewOffered: false,
+        },
+      ),
+    );
+  }
   if (o.hasQuestionnaire) middle.push('questionnaire');
   return [
-    'consent',
+    ...openingSteps(o),
     ...contactSteps(o),
     ...(o.hasCountrySelect ? (['country-select'] as KYCStep[]) : []),
     'id-type',
@@ -109,10 +193,20 @@ export function nextStepInOrder(step: KYCStep, o: StepOrderOptions): KYCStep {
   return order[index + 1] ?? order[order.length - 1]!;
 }
 
-/** The step before `step` — what the back button goes to. */
+/**
+ * The step before `step` — what the back button goes to.
+ *
+ * A step not in the order stands still, for the same reason `nextStepInOrder`
+ * refuses to guess at one: it has no predecessor in a flow that does not
+ * contain it. This used to fall through to `order[0]`, so an applicant resumed
+ * onto a step the flow had since dropped was thrown all the way back to consent
+ * by a single back-press, discarding everything they had done. Standing still
+ * is recoverable; that was not.
+ */
 export function previousStepInOrder(step: KYCStep, o: StepOrderOptions): KYCStep {
   const order = buildStepOrder(o);
   const index = order.indexOf(step);
-  if (index <= 0) return order[0]!;
+  if (index < 0) return step;
+  if (index === 0) return order[0]!;
   return order[index - 1]!;
 }

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/uploadLimits.ts

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// Upload size limits.
+//
+// One rule for every document the applicant attaches (proof of address, the
+// KYB company documents, the entrance photo): images up to 5 MB, PDFs up to
+// 15 MB (user decision 2026-09-06). The server's own cap is higher, so refusing
+// here gives an immediate, specific message instead of a slow 413. A THREE-WAY
+// MIRROR with the web SDK's `lib/upload-limits.ts` and Flutter's
+// `config/upload_limits.dart`, pinned to
+// `kyc-sdk-flutter/test/upload_limits_vectors.json`.
+// ---------------------------------------------------------------------------
+
+export const IMAGE_MAX_BYTES = 5 * 1024 * 1024;
+export const PDF_MAX_BYTES = 15 * 1024 * 1024;
+
+/** The line under every drop zone: what is accepted, and how big. */
+export const UPLOAD_HINT = 'PDF, JPG, PNG · PDF max 15 MB, images max 5 MB';
+
+export function isPdfMime(mime: string | null | undefined): boolean {
+  return (mime?.split(';')[0] ?? '').trim().toLowerCase() === 'application/pdf';
+}
+
+/**
+ * The refusal for a file over its cap, or null when it fits. An unknown size
+ * also passes: the server still judges the bytes at its own cap, and a picker
+ * that reports no size must not block a good file.
+ */
+export function uploadSizeError(
+  mime: string | null | undefined,
+  size: number | null | undefined,
+): string | null {
+  if (typeof size !== 'number' || !Number.isFinite(size)) return null;
+  if (isPdfMime(mime)) return size > PDF_MAX_BYTES ? 'PDF is too large (max 15 MB).' : null;
+  return size > IMAGE_MAX_BYTES ? 'Image is too large (max 5 MB).' : null;
+}

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

@@ -16,17 +16,22 @@
  */
 export const WORKFLOW_KEYS = [
   'subjectType',
+  'scope',
   'business',
   'country',
   'countries',
   'idTypes',
+  'multiId',
   'enableSelfie',
   'enableDocumentCapture',
   'allowDocumentUpload',
   'enableLiveness',
   'livenessMode',
   'flashSequenceLength',
+  'biometric',
   'deviceIntelligence',
+  'keyPeopleLinkRecovery',
+  'consentStep',
   'requireMobileDevice',
   'voiceGuidance',
   'showThemeToggle',
@@ -39,7 +44,10 @@ export const WORKFLOW_KEYS = [
   'phoneVerification',
   'questionnaire',
   'proofOfAddress',
+  'addressCollection',
   '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];
@@ -49,8 +57,10 @@ export type WorkflowKey = (typeof WORKFLOW_KEYS)[number];
  * key it DEFINES; an absent key leaves the prop alone (which is how a flow that
  * only sets, say, `livenessMode` doesn't wipe a prop-supplied `userId`).
  *
- * `appearance` merges shallowly with flow keys winning per-field, so a flow
- * that only sets `primaryColor` doesn't wipe a prop-supplied `logo`.
+ * `appearance` and `biometric` merge shallowly with flow keys winning
+ * per-field, so a flow that only sets `primaryColor` doesn't wipe a
+ * prop-supplied `logo`, and a flow that only switches the selfie review on
+ * doesn't wipe a host app's `doneButton: false`.
  *
  * Pure and side-effect free.
  */
@@ -63,10 +73,10 @@ export function mergeWorkflowConfig<P extends Record<string, unknown>>(
   for (const key of WORKFLOW_KEYS) {
     const value = flowConfig[key];
     if (value === undefined) continue;
-    if (key === 'appearance') {
-      const propAppearance = props['appearance'];
+    if (key === 'appearance' || key === 'biometric') {
+      const propBlock = props[key];
       merged[key] = {
-        ...(typeof propAppearance === 'object' && propAppearance !== null ? propAppearance : {}),
+        ...(typeof propBlock === 'object' && propBlock !== null ? propBlock : {}),
         ...(value as Record<string, unknown>),
       };
     } else {
@@ -96,6 +106,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';