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

package/src/emrtd/dg1.ts

@@ -0,0 +1,55 @@
+import { fromBase64 } from './bytes';
+import { findTlvDeep } from './der';
+import { parseMrz, type MrzScan } from '../mrz/parse';
+
+// ---------------------------------------------------------------------------
+// THE CHIP'S OWN MRZ.
+//
+// DG1 is the machine-readable zone exactly as the ISSUING STATE wrote it, and
+// passive authentication hashes it against the signed security object. It is
+// the strongest copy of the holder's details that exists on the document.
+//
+// The camera scan is a GUESS at the same characters, and it is not a safe
+// substitute for display. Measured on a real Nigerian passport read on a Galaxy
+// S24: the on-device recogniser read the first '<' of the '<<' surname
+// separator as 'K', so `INGWE<<RICHARD<UNIMKE` arrived as `INGWEK<RICHARD…`.
+// The split then never fired at the surname boundary and landed in the trailing
+// filler instead, yielding lastName "INGWEK RICHARD UNIMKE" and firstName
+// "KKKK" — displayed under a caption promising we had read the secure chip.
+//
+// TD3 carries NO check digit over the name field (only line 2 is protected), so
+// that corruption passes `parseMrz` validation silently. There is no way to
+// detect it from the scan alone, which is exactly why the chip has to be the
+// source once we hold it.
+//
+// Reuses `parseMrz` rather than parsing here: DG1's value IS the continuous
+// 88/90-character string that function already takes, and a second MRZ parser
+// would be one more thing to drift.
+// ---------------------------------------------------------------------------
+
+/** DG1's MRZ lives under tag 5F1F, inside the 0x61 template. */
+const TAG_MRZ = 0x5f1f;
+
+/**
+ * The MRZ read off the chip, or null when DG1 is absent, malformed, or not a
+ * size `parseMrz` recognises.
+ *
+ * Null is a normal outcome the caller falls back from, never an error: the
+ * read itself already succeeded and its bytes still go to the server, which
+ * parses DG1 authoritatively regardless of what this returns.
+ */
+export function parseDg1(dg1Base64: string | undefined | null): MrzScan | null {
+  if (!dg1Base64) return null;
+  try {
+    const bytes = fromBase64(dg1Base64);
+    const mrz = findTlvDeep(bytes, TAG_MRZ);
+    if (!mrz) return null;
+    let text = '';
+    for (const byte of mrz.value) text += String.fromCharCode(byte);
+    return parseMrz(text);
+  } catch {
+    // Display-path only. A malformed DG1 must never take down the success
+    // screen of a read that otherwise worked.
+    return null;
+  }
+}

package/src/emrtd/ec-curves.ts

@@ -0,0 +1,142 @@
+// ---------------------------------------------------------------------------
+// Standardised elliptic-curve domain parameters (ICAO 9303 / BSI TR-03110).
+//
+// A chip names its PACE curve by a standardised parameter id rather than
+// sending the parameters, so both sides must agree on this table. Every curve
+// here is a prime-field short-Weierstrass curve (y² = x³ + ax + b), so one set
+// of point arithmetic (ec.ts) covers all of them.
+//
+// The constants are transcribed from the authoritative sources — NIST FIPS
+// 186-4 for the secp/P- curves and RFC 5639 for the brainpool curves — and are
+// verified in ec.test.ts, which asserts G lies on each curve and that n·G is
+// the point at infinity. A transcription typo fails that test rather than a
+// passport.
+//
+// The six curves below are the ones issued eMRTDs actually use. The other
+// standardised ids (the 192/224-bit curves, DH groups) are left unmapped: an
+// unknown id resolves to null, which the caller treats exactly like a chip that
+// does not offer PACE — it reads over BAC. So the coverage gap can only ever
+// cost a fallback, never a failed read.
+// ---------------------------------------------------------------------------
+
+/** A prime-field short-Weierstrass curve and its generator. */
+export interface EcCurve {
+  readonly name: string;
+  /** Field prime. */
+  readonly p: bigint;
+  readonly a: bigint;
+  readonly b: bigint;
+  /** Generator coordinates. */
+  readonly gx: bigint;
+  readonly gy: bigint;
+  /** Group order. */
+  readonly n: bigint;
+  /** Field width in bytes — the fixed length x/y coordinates encode to. */
+  readonly byteLen: number;
+}
+
+const hex = (s: string): bigint => BigInt(`0x${s.replace(/\s+/g, '')}`);
+
+function curve(
+  name: string,
+  byteLen: number,
+  p: string,
+  a: string,
+  b: string,
+  gx: string,
+  gy: string,
+  n: string,
+): EcCurve {
+  return { name, byteLen, p: hex(p), a: hex(a), b: hex(b), gx: hex(gx), gy: hex(gy), n: hex(n) };
+}
+
+const secp256r1 = curve(
+  'secp256r1',
+  32,
+  'FFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFF',
+  'FFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFC',
+  '5AC635D8AA3A93E7B3EBBD55769886BC651D06B0CC53B0F63BCE3C3E27D2604B',
+  '6B17D1F2E12C4247F8BCE6E563A440F277037D812DEB33A0F4A13945D898C296',
+  '4FE342E2FE1A7F9B8EE7EB4A7C0F9E162BCE33576B315ECECBB6406837BF51F5',
+  'FFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551',
+);
+
+const brainpoolP256r1 = curve(
+  'brainpoolP256r1',
+  32,
+  'A9FB57DBA1EEA9BC3E660A909D838D726E3BF623D52620282013481D1F6E5377',
+  '7D5A0975FC2C3057EEF67530417AFFE7FB8055C126DC5C6CE94A4B44F330B5D9',
+  '26DC5C6CE94A4B44F330B5D9BBD77CBF958416295CF7E1CE6BCCDC18FF8C07B6',
+  '8BD2AEB9CB7E57CB2C4B482FFC81B7AFB9DE27E1E3BD23C23A4453BD9ACE3262',
+  '547EF835C3DAC4FD97F8461A14611DC9C27745132DED8E545C1D54C72F046997',
+  'A9FB57DBA1EEA9BC3E660A909D838D718C397AA3B561A6F7901E0E82974856A7',
+);
+
+const secp384r1 = curve(
+  'secp384r1',
+  48,
+  'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFF0000000000000000FFFFFFFF',
+  'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFF0000000000000000FFFFFFFC',
+  'B3312FA7E23EE7E4988E056BE3F82D19181D9C6EFE8141120314088F5013875AC656398D8A2ED19D2A85C8EDD3EC2AEF',
+  'AA87CA22BE8B05378EB1C71EF320AD746E1D3B628BA79B9859F741E082542A385502F25DBF55296C3A545E3872760AB7',
+  '3617DE4A96262C6F5D9E98BF9292DC29F8F41DBD289A147CE9DA3113B5F0B8C00A60B1CE1D7E819D7A431D7C90EA0E5F',
+  'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC7634D81F4372DDF581A0DB248B0A77AECEC196ACCC52973',
+);
+
+const brainpoolP384r1 = curve(
+  'brainpoolP384r1',
+  48,
+  '8CB91E82A3386D280F5D6F7E50E641DF152F7109ED5456B412B1DA197FB71123ACD3A729901D1A71874700133107EC53',
+  '7BC382C63D8C150C3C72080ACE05AFA0C2BEA28E4FB22787139165EFBA91F90F8AA5814A503AD4EB04A8C7DD22CE2826',
+  '04A8C7DD22CE28268B39B55416F0447C2FB77DE107DCD2A62E880EA53EEB62D57CB4390295DBC9943AB78696FA504C11',
+  '1D1C64F068CF45FFA2A63A81B7C13F6B8847A3E77EF14FE3DB7FCAFE0CBD10E8E826E03436D646AAEF87B2E247D4AF1E',
+  '8ABE1D7520F9C2A45CB1EB8E95CFD55262B70B29FEEC5864E19C054FF99129280E4646217791811142820341263C5315',
+  '8CB91E82A3386D280F5D6F7E50E641DF152F7109ED5456B31F166E6CAC0425A7CF3AB6AF6B7FC3103B883202E9046565',
+);
+
+const brainpoolP512r1 = curve(
+  'brainpoolP512r1',
+  64,
+  'AADD9DB8DBE9C48B3FD4E6AE33C9FC07CB308DB3B3C9D20ED6639CCA703308717D4D9B009BC66842AECDA12AE6A380E62881FF2F2D82C68528AA6056583A48F3',
+  '7830A3318B603B89E2327145AC234CC594CBDD8D3DF91610A83441CAEA9863BC2DED5D5AA8253AA10A2EF1C98B9AC8B57F1117A72BF2C7B9E7C1AC4D77FC94CA',
+  '3DF91610A83441CAEA9863BC2DED5D5AA8253AA10A2EF1C98B9AC8B57F1117A72BF2C7B9E7C1AC4D77FC94CADC083E67984050B75EBAE5DD2809BD638016F723',
+  '81AEE4BDD82ED9645A21322E9C4C6A9385ED9F70B5D916C1B43B62EEF4D0098EFF3B1F78E2D0D48D50D1687B93B97D5F7C6D5047406A5E688B352209BCB9F822',
+  '7DDE385D566332ECC0EABFA9CF7822FDF209F70024A57B1AA000C55B881F8111B2DCDE494A5F485E5BCA4BD88A2763AED1CA2B2FA8F0540678CD1E0F3AD80892',
+  'AADD9DB8DBE9C48B3FD4E6AE33C9FC07CB308DB3B3C9D20ED6639CCA70330870553E5C414CA92619418661197FAC10471DB1D381085DDADDB58796829CA90069',
+);
+
+const secp521r1 = curve(
+  'secp521r1',
+  66,
+  '01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF',
+  '01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC',
+  '0051953EB9618E1C9A1F929A21A0B68540EEA2DA725B99B315F3B8B489918EF109E156193951EC7E937B1652C0BD3BB1BF073573DF883D2C34F1EF451FD46B503F00',
+  '00C6858E06B70404E9CD9E3ECB662395B4429C648139053FB521F828AF606B4D3DBAA14B5E77EFE75928FE1DC127A2FFA8DE3348B3C1856A429BF97E7E31C2E5BD66',
+  '011839296A789A3BC0045C8A5FB42C7D1BD998F54449579B446817AFBD17273E662C97EE72995EF42640C550B9013FAD0761353C7086A272C24088BE94769FD16650',
+  '01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA51868783BF2F966B7FCC0148F709A5D03BB5C9B8899C47AEBB6FB71E91386409',
+);
+
+/** ICAO standardised parameter id → curve, for the curves this build runs. */
+const BY_ID: Record<number, EcCurve> = {
+  12: secp256r1,
+  13: brainpoolP256r1,
+  15: secp384r1,
+  16: brainpoolP384r1,
+  17: brainpoolP512r1,
+  18: secp521r1,
+};
+
+/** The curve for a standardised parameter id, or null when unmapped. */
+export function curveForParameterId(id: number): EcCurve | null {
+  return BY_ID[id] ?? null;
+}
+
+/** Exposed for tests — every curve this build claims to support. */
+export const ALL_CURVES: readonly EcCurve[] = [
+  secp256r1,
+  brainpoolP256r1,
+  secp384r1,
+  brainpoolP384r1,
+  brainpoolP512r1,
+  secp521r1,
+];

package/src/emrtd/ec.ts

@@ -0,0 +1,196 @@
+import type { EcCurve } from './ec-curves';
+
+// ---------------------------------------------------------------------------
+// Elliptic-curve point arithmetic over a prime field, in BigInt.
+//
+// WHY THIS IS IN TYPESCRIPT while the block ciphers are native. The native side
+// exposes 3DES/AES/SHA/CMAC because those are audited, constant-time, hardware
+// -accelerated platform primitives. It exposes no EC point arithmetic, and
+// adding it would mean writing and shipping matching Swift and Kotlin — two
+// more implementations of the same maths, on the path that authenticates a
+// passport. One implementation, checked against the curve's own published
+// generator and order (ec.test.ts), is the smaller risk.
+//
+// The scalar multiply is a fixed-sequence Montgomery ladder: every bit of the
+// scalar performs the same add-then-double regardless of its value, so the
+// operation sequence does not depend on the secret. That is as far as constant
+// time goes here — BigInt itself is variable-time, so this is not hardened
+// against a local timing attacker. It does not need to be: the private scalar
+// is ephemeral, used for exactly one handshake with a chip held against the
+// phone, and discarded.
+// ---------------------------------------------------------------------------
+
+/** An affine point, or the point at infinity (`inf`). */
+export interface EcPoint {
+  readonly x: bigint;
+  readonly y: bigint;
+  readonly inf: boolean;
+}
+
+export const INFINITY: EcPoint = { x: 0n, y: 0n, inf: true };
+
+export function point(x: bigint, y: bigint): EcPoint {
+  return { x, y, inf: false };
+}
+
+/** Least non-negative residue — `%` alone keeps the sign of the dividend. */
+function mod(a: bigint, p: bigint): bigint {
+  const r = a % p;
+  return r < 0n ? r + p : r;
+}
+
+/**
+ * Modular inverse by the extended Euclidean algorithm.
+ *
+ * Throws when the value is not invertible, which for a prime field means it was
+ * congruent to zero. Callers reach this only through point arithmetic that has
+ * already excluded the cases where that happens.
+ */
+export function modInverse(value: bigint, p: bigint): bigint {
+  let [old_r, r] = [mod(value, p), p];
+  let [old_s, s] = [1n, 0n];
+  while (r !== 0n) {
+    const q = old_r / r;
+    [old_r, r] = [r, old_r - q * r];
+    [old_s, s] = [s, old_s - q * s];
+  }
+  if (old_r !== 1n) throw new Error('value is not invertible');
+  return mod(old_s, p);
+}
+
+/** Whether the point satisfies y² = x³ + ax + b over the curve's field. */
+export function isOnCurve(c: EcCurve, pt: EcPoint): boolean {
+  if (pt.inf) return false;
+  if (pt.x < 0n || pt.x >= c.p || pt.y < 0n || pt.y >= c.p) return false;
+  const lhs = mod(pt.y * pt.y, c.p);
+  const rhs = mod(pt.x * pt.x * pt.x + c.a * pt.x + c.b, c.p);
+  return lhs === rhs;
+}
+
+export function pointDouble(c: EcCurve, pt: EcPoint): EcPoint {
+  if (pt.inf) return INFINITY;
+  // A point with y = 0 is its own inverse, so doubling it lands on infinity.
+  if (pt.y === 0n) return INFINITY;
+  const lambda = mod(
+    (3n * pt.x * pt.x + c.a) * modInverse(2n * pt.y, c.p),
+    c.p,
+  );
+  const x = mod(lambda * lambda - 2n * pt.x, c.p);
+  return point(x, mod(lambda * (pt.x - x) - pt.y, c.p));
+}
+
+export function pointAdd(c: EcCurve, a: EcPoint, b: EcPoint): EcPoint {
+  if (a.inf) return b;
+  if (b.inf) return a;
+  if (a.x === b.x) {
+    // Same x: either the same point (double) or inverses (sum is infinity).
+    return mod(a.y + b.y, c.p) === 0n ? INFINITY : pointDouble(c, a);
+  }
+  const lambda = mod((b.y - a.y) * modInverse(b.x - a.x, c.p), c.p);
+  const x = mod(lambda * lambda - a.x - b.x, c.p);
+  return point(x, mod(lambda * (a.x - x) - a.y, c.p));
+}
+
+/**
+ * Scalar multiplication by a Montgomery ladder.
+ *
+ * Both branches of every bit do the same work, so the sequence of field
+ * operations is independent of the scalar's bits (see the header note on how
+ * far that guarantee goes). The ladder starts at the scalar's own bit width
+ * rather than the curve's, which is safe here because the scalar is uniformly
+ * random in [1, n-1] and never a low-entropy value whose bit length would leak
+ * something meaningful.
+ */
+export function pointMultiply(c: EcCurve, k: bigint, pt: EcPoint): EcPoint {
+  if (k <= 0n || pt.inf) return INFINITY;
+  let r0: EcPoint = INFINITY;
+  let r1: EcPoint = pt;
+  for (let i = BigInt(k.toString(2).length) - 1n; i >= 0n; i--) {
+    if (((k >> i) & 1n) === 0n) {
+      r1 = pointAdd(c, r0, r1);
+      r0 = pointDouble(c, r0);
+    } else {
+      r0 = pointAdd(c, r0, r1);
+      r1 = pointDouble(c, r1);
+    }
+  }
+  return r0;
+}
+
+/** The curve's generator as a point. */
+export function generator(c: EcCurve): EcPoint {
+  return point(c.gx, c.gy);
+}
+
+// ── Encoding ────────────────────────────────────────────────────────────────
+
+/** Big-endian bytes → integer. */
+export function bytesToBigInt(bytes: Uint8Array): bigint {
+  let n = 0n;
+  for (const b of bytes) n = (n << 8n) | BigInt(b);
+  return n;
+}
+
+/**
+ * Integer → fixed-width big-endian bytes.
+ *
+ * The width is fixed on purpose: a shared secret whose x coordinate happens to
+ * start with a zero byte must still derive the same-length key material, and a
+ * variable-length encoding there silently produces the wrong session keys on
+ * roughly one handshake in 256.
+ */
+export function bigIntToBytes(value: bigint, width: number): Uint8Array {
+  const out = new Uint8Array(width);
+  let v = value;
+  for (let i = width - 1; i >= 0 && v > 0n; i--) {
+    out[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return out;
+}
+
+/** Uncompressed point encoding: 0x04 || X || Y, each coordinate field-width. */
+export function encodePoint(c: EcCurve, pt: EcPoint): Uint8Array {
+  if (pt.inf) throw new Error('cannot encode the point at infinity');
+  const out = new Uint8Array(1 + c.byteLen * 2);
+  out[0] = 0x04;
+  out.set(bigIntToBytes(pt.x, c.byteLen), 1);
+  out.set(bigIntToBytes(pt.y, c.byteLen), 1 + c.byteLen);
+  return out;
+}
+
+/**
+ * Decode an uncompressed point, returning null when the bytes are not a valid
+ * point on the curve.
+ *
+ * Validation is the security-critical part, not a formality: a chip that picks
+ * a point off the curve (or a small-order point on a related curve) can learn
+ * our private scalar from how we respond, so anything that does not verify is
+ * refused rather than used. Compressed encodings are rejected too, since PACE
+ * mandates the uncompressed form and accepting more would only widen what an
+ * attacker can hand us.
+ */
+export function decodePoint(c: EcCurve, bytes: Uint8Array): EcPoint | null {
+  if (bytes.length !== 1 + c.byteLen * 2 || bytes[0] !== 0x04) return null;
+  const pt = point(
+    bytesToBigInt(bytes.subarray(1, 1 + c.byteLen)),
+    bytesToBigInt(bytes.subarray(1 + c.byteLen)),
+  );
+  return isOnCurve(c, pt) ? pt : null;
+}
+
+/**
+ * A uniformly random private scalar in [1, n-1].
+ *
+ * Rejection sampling rather than a modulo: reducing a random integer mod n
+ * biases the result toward small values, and biased nonces are how ECDSA keys
+ * have historically been recovered. The loop is bounded because each draw
+ * succeeds with probability very close to 1 for every curve here.
+ */
+export function randomScalar(c: EcCurve, randomBytes: (n: number) => Uint8Array): bigint {
+  for (let attempt = 0; attempt < 64; attempt++) {
+    const candidate = bytesToBigInt(randomBytes(c.byteLen));
+    if (candidate > 0n && candidate < c.n) return candidate;
+  }
+  throw new Error('could not draw a private scalar');
+}

package/src/emrtd/index.ts

@@ -26,5 +26,6 @@ export {
   nfcStageLabel,
   nfcStageProgress,
 } from './stages';
+export { parseDg1 } from './dg1';
 export { decodeChipImage, isNfcAvailable, nfcUnavailableReason } from './native';
 export { cancelChipRead, readPassportChip, type ChipReadOptions } from './read';

package/src/emrtd/mrzKey.ts

@@ -48,7 +48,27 @@ export function mrzKeySeedInput(fields: MrzKeyFields): string {
   );
 }
 
-/** Kseed: the first 16 bytes of SHA-1 over the MRZ information. */
+/** Kseed for BAC: the first 16 bytes of SHA-1 over the MRZ information. */
 export function keySeed(p: EmrtdPrimitives, fields: MrzKeyFields): Uint8Array {
   return p.sha1(fromAscii(mrzKeySeedInput(fields))).subarray(0, 16);
 }
+
+/**
+ * The seed PACE derives its password key from: the FULL SHA-1 digest, NOT
+ * truncated to 16 bytes.
+ *
+ * This is the one place the two protocols disagree about the same hash, and it
+ * is silent when wrong: a truncated seed yields a valid-looking K_π, the
+ * handshake runs to its last step, and the chip answers 0x6300 — which reads
+ * exactly like a mistyped MRZ rather than a derivation bug. It cost this SDK a
+ * real passport read to find (the same document opened over BAC moments later,
+ * proving the MRZ was right).
+ *
+ * ICAO 9303 Part 11 keeps the two apart: §9.7.3 truncates for BAC's Kseed,
+ * while §9.7.2 feeds the whole digest to KDF_π. JMRTD encodes the same split as
+ * `computeKeySeedForBAC(… truncate: true)` vs `computeKeySeedForPACE(…
+ * truncate: false)`.
+ */
+export function paceKeySeed(p: EmrtdPrimitives, fields: MrzKeyFields): Uint8Array {
+  return p.sha1(fromAscii(mrzKeySeedInput(fields)));
+}

package/src/emrtd/open.ts

@@ -0,0 +1,169 @@
+import { fromBase64, toBase64 } from './bytes';
+import type { EmrtdPrimitives, MrzKeyFields } from './crypto';
+import { paceKeySeed } from './crypto';
+import { curveForParameterId } from './ec-curves';
+import { runPaceEcdhGm, PaceError, type PaceTransceive } from './pace';
+import {
+  describeProtocol,
+  paceGapFor,
+  parseCardAccess,
+  selectPaceOffer,
+} from './pace-params';
+import type { SecureMessagingSession } from './secureMessaging';
+import type { EmrtdTransport } from './session';
+
+// ---------------------------------------------------------------------------
+// Choosing how to get into the chip.
+//
+// A chip may accept BAC, PACE, or both, and this decides which is tried first.
+//
+// The standard prefers PACE, and so should we eventually: BAC derives its keys
+// from the MRZ alone, so anyone who photographs the passport page can decrypt a
+// recorded session afterwards, while PACE agrees fresh keys every time.
+//
+// But this SDK's BAC has been reading real passports for a long time and its
+// PACE has not read any, so the default here is deliberately the other way
+// round: BAC first, PACE only when BAC is refused. In that order PACE can only
+// ever ADD documents we can read — chips that have retired BAC — and can never
+// take away one that already worked.
+//
+// PACE has since been confirmed against a real document — a Nigerian e-passport
+// on 2026-08-11, over PACE-ECDH-GM with AES-256 on brainpoolP256r1, on both an
+// iPhone 16 Pro Max and a Galaxy S24, with passive authentication passing and
+// the DG2 portrait read. So the code is no longer unproven.
+//
+// The ordering STAYS BAC-first anyway, which is the part worth explaining:
+// "confirmed on one document" is not "confirmed on the population". BAC has
+// read every passport this SDK has ever seen; PACE has read one model of one
+// issuer's. Going PACE-first would put the less-travelled path in front of
+// every document in the world to buy a property (forward secrecy against a
+// recorded session) that matters far less than reading the passport at all.
+//
+// PACE still runs — as the fallback, where it can only ever ADD documents we
+// can read, namely chips that have retired BAC. Revisit when PACE has spanned
+// several issuers, not before.
+//
+// Mirrors the Flutter SDK's emrtd_open.dart, including this reasoning.
+// ---------------------------------------------------------------------------
+
+/**
+ * Which access protocol is tried first.
+ *
+ * `false` (the shipping default) means BAC first, PACE only if BAC is refused.
+ * `true` reverses it, which is how PACE gets exercised against a real chip: a
+ * passport that accepts BAC would otherwise never reach the PACE code at all.
+ * Set it to `true` temporarily to test PACE against a document; do not ship it.
+ *
+ * Safe either way — whichever goes first, the other still runs as the fallback,
+ * so this cannot turn a readable document into an unreadable one.
+ */
+export const PREFER_PACE = false;
+
+/**
+ * Why a session ended up on the protocol it did.
+ *
+ * The protocol name alone cannot answer the question that matters while PACE is
+ * new: a chip reading over BAC may never have OFFERED PACE, or may have offered
+ * it and had our implementation fail. Those call for opposite responses — one
+ * is nothing to do, the other is a bug — so the reason is recorded rather than
+ * inferred.
+ */
+export type PaceOutcome =
+  /** PACE opened the session. */
+  | 'used'
+  /** The chip published no EF.CardAccess: it does not speak PACE at all. */
+  | 'notOffered'
+  /** EF.CardAccess offers only variants this build cannot run. */
+  | 'unsupportedVariant'
+  /** PACE was attempted and did not complete. THIS is the one worth chasing. */
+  | 'failed'
+  /** Not tried — BAC succeeded first. */
+  | 'notAttempted';
+
+export interface AccessResult {
+  sm: SecureMessagingSession;
+  /** Which protocol secured the session. */
+  chipAuth: 'bac' | 'pace';
+  outcome: PaceOutcome;
+  /** The negotiated protocol when PACE was used, or why it was not. */
+  detail?: string;
+}
+
+/** EF.CardAccess: at the Master File, readable with no session at all. */
+const EF_CARD_ACCESS = 0x011c;
+
+/**
+ * Read EF.CardAccess, or null when the chip does not offer it — which simply
+ * means BAC. Absent, unreadable, and unparseable all mean the same thing to
+ * the caller, so none of them throw.
+ */
+export async function readCardAccess(transport: EmrtdTransport): Promise<Uint8Array | null> {
+  try {
+    // SELECT the Master File, then EF.CardAccess by identifier.
+    const mf = await transport.transceive(
+      toBase64(new Uint8Array([0x00, 0xa4, 0x00, 0x0c, 0x02, 0x3f, 0x00])),
+    );
+    if (mf.statusWord !== 0x9000) return null;
+    const select = await transport.transceive(
+      toBase64(
+        new Uint8Array([0x00, 0xa4, 0x02, 0x0c, 0x02, (EF_CARD_ACCESS >> 8) & 0xff, EF_CARD_ACCESS & 0xff]),
+      ),
+    );
+    if (select.statusWord !== 0x9000) return null;
+    const read = await transport.transceive(
+      toBase64(new Uint8Array([0x00, 0xb0, 0x00, 0x00, 0x00])),
+    );
+    if (read.statusWord !== 0x9000) return null;
+    const data = fromBase64(read.data);
+    return data.length > 0 ? data : null;
+  } catch {
+    return null; // absent or unreadable — the caller falls back to BAC
+  }
+}
+
+/**
+ * Try PACE. Resolves with the session when it worked, or reports why it did
+ * not — a `null` result always means "fall back to BAC", never a failed read.
+ */
+export async function tryPace(
+  p: EmrtdPrimitives,
+  transport: EmrtdTransport,
+  mrz: MrzKeyFields,
+): Promise<{ sm: SecureMessagingSession; detail: string } | { outcome: PaceOutcome; detail?: string }> {
+  const file = await readCardAccess(transport);
+  if (!file) return { outcome: 'notOffered' };
+
+  const offers = parseCardAccess(file);
+  const selected = selectPaceOffer(offers);
+  if (!selected) {
+    return { outcome: 'unsupportedVariant', detail: paceGapFor(offers) ?? undefined };
+  }
+
+  const { offer, curve } = selected;
+  // The MRZ unlocks the chip's nonce rather than the session itself: counter 3
+  // is the password key, where BAC uses 1 and 2 for its session keys. The seed
+  // is the UNTRUNCATED SHA-1 — see paceKeySeed for why that distinction matters
+  // and how it fails when it is wrong.
+  const passwordKey = offer.protocol.suite.deriveKey(p, paceKeySeed(p, mrz), 3);
+
+  const transceive: PaceTransceive = async (command) => {
+    const res = await transport.transceive(toBase64(command));
+    return { data: fromBase64(res.data), statusWord: res.statusWord };
+  };
+
+  const sm = await runPaceEcdhGm({
+    p,
+    transceive,
+    protocol: offer.protocol,
+    curve,
+    passwordKey,
+  });
+  return { sm, detail: `${describeProtocol(offer.protocol)} params=${offer.parameterId}` };
+}
+
+/** Whether a parameter id resolves to a curve this build runs. Test seam. */
+export function supportsParameterId(id: number): boolean {
+  return curveForParameterId(id) !== null;
+}
+
+export { PaceError };