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

package/src/emrtd/pace.ts

@@ -0,0 +1,295 @@
+import { concat, timingSafeEqual, unpadFromBlock } from './bytes';
+import { encodeTlv, findTlv, readTlv } from './der';
+import type { EcCurve } from './ec-curves';
+import {
+  bigIntToBytes,
+  bytesToBigInt,
+  decodePoint,
+  encodePoint,
+  generator,
+  pointAdd,
+  pointMultiply,
+  randomScalar,
+  type EcPoint,
+} from './ec';
+import type { EmrtdPrimitives } from './crypto';
+import { SecureMessagingSession } from './secureMessaging';
+import type { PaceProtocol } from './pace-params';
+
+// ---------------------------------------------------------------------------
+// PACE, Generic Mapping over elliptic curves (ICAO 9303 Part 11 §4.4).
+//
+// The newer way into a chip. BAC derives its keys straight from the MRZ, so an
+// attacker who photographs the passport page can decrypt a recorded session
+// forever. PACE uses the MRZ only to unlock a fresh random nonce, then runs a
+// Diffie-Hellman exchange over a generator derived from it — so the session
+// keys are new every time and the MRZ alone never reveals them.
+//
+// The handshake is four exchanges after a setup command:
+//
+//   0. MSE:Set AT      name the protocol and which password we hold
+//   1. get nonce       chip sends a nonce encrypted under the password key
+//   2. map nonce       both sides contribute a key; the nonce and the shared
+//                      secret combine into a fresh generator
+//   3. key agreement   a second exchange over THAT generator gives the session
+//                      secret, and the session keys derive from it
+//   4. mutual auth     each side proves it derived the same keys, by MACing
+//                      the other's public key
+//
+// Steps 1-3 are sent with the command-chaining class byte; step 4 closes the
+// chain. Getting that wrong makes a chip abandon the handshake midway.
+//
+// Mirrors the Flutter SDK's emrtd_pace.dart step for step, so a chip that reads
+// on one platform reads on the other.
+// ---------------------------------------------------------------------------
+
+export class PaceError extends Error {
+  constructor(
+    message: string,
+    /**
+     * `auth_failed` when the chip refuses the password, which in practice
+     * always means a wrong MRZ. Anything else is a protocol or transport fault.
+     */
+    readonly code: 'auth_failed' | 'read_failed',
+  ) {
+    super(message);
+    this.name = 'PaceError';
+    Object.setPrototypeOf(this, PaceError.prototype);
+  }
+}
+
+/** Data objects inside the dynamic authentication template, by step. */
+const DO = {
+  template: 0x7c,
+  encryptedNonce: 0x80,
+  mappingCommand: 0x81,
+  mappingResponse: 0x82,
+  keyCommand: 0x83,
+  keyResponse: 0x84,
+  tokenCommand: 0x85,
+  tokenResponse: 0x86,
+  publicKey: 0x7f49,
+  objectIdentifier: 0x06,
+  ecPoint: 0x86,
+} as const;
+
+const SW_OK = 0x9000;
+
+/** Sends one raw APDU and returns the response data with its status word. */
+export type PaceTransceive = (
+  command: Uint8Array,
+) => Promise<{ data: Uint8Array; statusWord: number }>;
+
+/**
+ * Run PACE-GM over an elliptic curve and return the secured session.
+ *
+ * `passwordKey` is the MRZ-derived password key (counter 3), NOT a session key
+ * — PACE uses the MRZ only to unlock the chip's nonce.
+ */
+export async function runPaceEcdhGm(options: {
+  p: EmrtdPrimitives;
+  transceive: PaceTransceive;
+  protocol: PaceProtocol;
+  curve: EcCurve;
+  passwordKey: Uint8Array;
+  /** Injectable for tests; production draws real randomness. */
+  fixed?: { mapPrivate?: bigint; sessionPrivate?: bigint };
+}): Promise<SecureMessagingSession> {
+  const { p, transceive, protocol, curve, passwordKey } = options;
+  const suite = protocol.suite;
+
+  // Step 0 — announce the protocol and which password we are using. No Le:
+  // MSE:Set AT returns no data, and appending one makes it a case-4 command
+  // the chip answers 0x6700 "wrong length" to.
+  await exchange(
+    transceive,
+    concat(
+      new Uint8Array([0x00, 0x22, 0xc1, 0xa4]),
+      body(
+        [encodeTlv(0x80, protocol.oid), encodeTlv(0x83, new Uint8Array([0x01]))],
+        false,
+      ),
+    ),
+    'select',
+  );
+
+  // Step 1 — the chip's nonce, encrypted under the password key. A chip that
+  // refuses here has decided the password is wrong.
+  const nonceReply = await generalAuthenticate(
+    transceive,
+    encodeTlv(DO.template, new Uint8Array(0)),
+    false,
+    'nonce',
+  );
+  // No unpadding: the nonce is whole blocks of random, not a padded message.
+  const nonce = suite.decrypt(p, passwordKey, expect(nonceReply, DO.encryptedNonce, 'nonce'));
+
+  // Step 2 — map the nonce onto a fresh generator. Each side sends an ephemeral
+  // public key; the shared point plus the nonce give a generator neither side
+  // chose alone.
+  const mapPrivate = options.fixed?.mapPrivate ?? randomScalar(curve, p.randomBytes);
+  const mapPublic = pointMultiply(curve, mapPrivate, generator(curve));
+  const mapReply = await generalAuthenticate(
+    transceive,
+    encodeTlv(DO.template, encodeTlv(DO.mappingCommand, encodePoint(curve, mapPublic))),
+    false,
+    'mapping',
+  );
+  const chipMapPoint = decodeChipPoint(curve, expect(mapReply, DO.mappingResponse, 'mapping'));
+
+  const shared = pointMultiply(curve, mapPrivate, chipMapPoint);
+  const mappedGenerator = pointAdd(
+    curve,
+    pointMultiply(curve, bytesToBigInt(nonce) % curve.n, generator(curve)),
+    shared,
+  );
+  if (mappedGenerator.inf) {
+    throw new PaceError('The mapped generator was degenerate.', 'read_failed');
+  }
+
+  // Step 3 — the real key agreement, over the mapped generator.
+  const sessionPrivate = options.fixed?.sessionPrivate ?? randomScalar(curve, p.randomBytes);
+  const sessionPublic = pointMultiply(curve, sessionPrivate, mappedGenerator);
+  const keyReply = await generalAuthenticate(
+    transceive,
+    encodeTlv(DO.template, encodeTlv(DO.keyCommand, encodePoint(curve, sessionPublic))),
+    false,
+    'key agreement',
+  );
+  const chipSessionPoint = decodeChipPoint(
+    curve,
+    expect(keyReply, DO.keyResponse, 'key agreement'),
+  );
+
+  // Identical public keys mean the exchange contributed nothing.
+  if (chipSessionPoint.x === sessionPublic.x && chipSessionPoint.y === sessionPublic.y) {
+    throw new PaceError('The chip echoed our public key.', 'read_failed');
+  }
+
+  const agreed = pointMultiply(curve, sessionPrivate, chipSessionPoint);
+  if (agreed.inf) {
+    throw new PaceError('Key agreement produced no secret.', 'read_failed');
+  }
+  // The shared secret is the agreed point's x coordinate, left-padded to the
+  // curve's field width: a short value must not shorten the key derivation.
+  const secret = bigIntToBytes(agreed.x, curve.byteLen);
+
+  const ksEnc = suite.deriveKey(p, secret, 1);
+  const ksMac = suite.deriveKey(p, secret, 2);
+
+  // Step 4 — each side MACs the OTHER side's public key. Matching tokens prove
+  // both derived the same session keys without either revealing them.
+  const ourToken = suite.token(p, ksMac, tokenInput(curve, protocol.oid, chipSessionPoint));
+  const tokenReply = await generalAuthenticate(
+    transceive,
+    encodeTlv(DO.template, encodeTlv(DO.tokenCommand, ourToken)),
+    true,
+    'authentication',
+  );
+  const chipToken = expect(tokenReply, DO.tokenResponse, 'authentication');
+  const expected = suite.token(p, ksMac, tokenInput(curve, protocol.oid, sessionPublic));
+  if (!timingSafeEqual(chipToken, expected)) {
+    throw new PaceError(
+      'The chip proved a different key. The document details do not match.',
+      'auth_failed',
+    );
+  }
+
+  // A PACE session starts its counter at zero, unlike BAC's nonce-derived one.
+  return new SecureMessagingSession(p, { ksEnc, ksMac }, new Uint8Array(suite.blockSize), suite);
+}
+
+/**
+ * GENERAL AUTHENTICATE. Steps before the last are sent with the chaining class
+ * byte, which tells the chip more of the same command is coming.
+ */
+async function generalAuthenticate(
+  transceive: PaceTransceive,
+  data: Uint8Array,
+  last: boolean,
+  step: string,
+): Promise<Uint8Array> {
+  const command = concat(
+    new Uint8Array([last ? 0x00 : 0x10, 0x86, 0x00, 0x00]),
+    body([data], true),
+  );
+  const response = await exchange(transceive, command, step);
+  const template = readTlv(response);
+  if (!template || template.tag !== DO.template) {
+    throw new PaceError(`The ${step} reply was not authentication data.`, 'read_failed');
+  }
+  return template.value;
+}
+
+async function exchange(
+  transceive: PaceTransceive,
+  command: Uint8Array,
+  step: string,
+): Promise<Uint8Array> {
+  const { data, statusWord } = await transceive(command);
+  if (statusWord !== SW_OK) {
+    // 0x6300 and 0x63CX are how chips say the password was wrong; some older
+    // ones use the latter specifically for bad session data.
+    const wrongPassword = statusWord === 0x6300 || (statusWord & 0xfff0) === 0x63c0;
+    throw new PaceError(
+      // The STEP is in both messages on purpose. A refusal at 'authentication'
+      // means our token did not match, which points at the password key
+      // derivation; one at 'nonce' means the chip would not even start. Without
+      // the step both read as "wrong MRZ" and send debugging the wrong way —
+      // which is exactly what happened the first time this ran against a real
+      // passport.
+      wrongPassword
+        ? `The chip rejected the document details at the ${step} step.`
+        : `The chip returned ${statusWord.toString(16).padStart(4, '0')} at the ${step} step.`,
+      wrongPassword ? 'auth_failed' : 'read_failed',
+    );
+  }
+  return data;
+}
+
+function expect(template: Uint8Array, tag: number, step: string): Uint8Array {
+  const found = findTlv(template, tag);
+  if (!found) {
+    throw new PaceError(`The ${step} reply was missing its data.`, 'read_failed');
+  }
+  return found.value;
+}
+
+/** A chip-supplied point, validated before any arithmetic touches it. */
+function decodeChipPoint(curve: EcCurve, bytes: Uint8Array): EcPoint {
+  const pt = decodePoint(curve, bytes);
+  // A point off the curve or at infinity would leak our private scalar to a
+  // chip that chose it deliberately, so it is refused rather than used.
+  if (!pt) throw new PaceError('The chip sent an invalid key.', 'read_failed');
+  return pt;
+}
+
+/**
+ * The object each side MACs to prove it holds the session keys: the protocol
+ * identifier and the other party's public point.
+ */
+function tokenInput(curve: EcCurve, oid: Uint8Array, pt: EcPoint): Uint8Array {
+  return encodeTlv(
+    DO.publicKey,
+    concat(encodeTlv(DO.objectIdentifier, oid), encodeTlv(DO.ecPoint, encodePoint(curve, pt))),
+  );
+}
+
+/**
+ * Lc, body, and Le only when the command actually returns data.
+ *
+ * ISO 7816 distinguishes a command that sends data (case 3) from one that
+ * sends and receives (case 4) by the presence of that trailing byte, and a
+ * chip asked for a response it has none of replies 0x6700.
+ */
+function body(parts: Uint8Array[], expectsResponse: boolean): Uint8Array {
+  const joined = concat(...parts);
+  return concat(
+    new Uint8Array([joined.length]),
+    joined,
+    expectsResponse ? new Uint8Array([0x00]) : new Uint8Array(0),
+  );
+}
+
+/** Re-exported so the session can strip padding from a PACE-decrypted body. */
+export { unpadFromBlock };

package/src/emrtd/secureMessaging.ts

@@ -1,13 +1,7 @@
 import { concat, padToBlock, timingSafeEqual, unpadFromBlock } from './bytes';
 import { encodeTlv, readTlvSequence } from './der';
-import {
-  BLOCK_SIZE,
-  decrypt3Des,
-  encrypt3Des,
-  macWithPadding,
-  type EmrtdPrimitives,
-  type SessionKeys,
-} from './crypto';
+import type { EmrtdPrimitives, SessionKeys } from './crypto';
+import { DES_EDE2_SUITE, type CipherSuite } from './suites';
 
 // ---------------------------------------------------------------------------
 // Secure messaging (ICAO 9303 Part 11 §9.8).
@@ -61,6 +55,13 @@ export class SecureMessagingSession {
     private readonly p: EmrtdPrimitives,
     private readonly keys: SessionKeys,
     initialSsc: Uint8Array,
+    /**
+     * Which cipher the session runs on. BAC is always 3DES (the default, so
+     * every existing call site is unchanged); a PACE session may have
+     * negotiated AES, which changes the block size, the padding unit, the
+     * counter width and how the IV is derived.
+     */
+    private readonly suite: CipherSuite = DES_EDE2_SUITE,
   ) {
     this.ssc = new Uint8Array(initialSsc);
   }
@@ -80,15 +81,21 @@ export class SecureMessagingSession {
     // The class byte gains the secure-messaging bits, and the MAC is computed
     // over the PADDED header — a detail the standard is easy to misread.
     const cla = apdu.cla | 0x0c;
+    const block = this.suite.blockSize;
     const header = padToBlock(
       new Uint8Array([cla, apdu.ins, apdu.p1, apdu.p2]),
-      BLOCK_SIZE,
+      block,
     );
 
     const parts: Uint8Array[] = [];
 
     if (apdu.data && apdu.data.length > 0) {
-      const encrypted = encrypt3Des(this.p, this.keys.ksEnc, padToBlock(apdu.data, BLOCK_SIZE));
+      const encrypted = this.suite.encrypt(
+        this.p,
+        this.keys.ksEnc,
+        padToBlock(apdu.data, block),
+        this.ssc,
+      );
       // The leading 0x01 is the padding-content indicator: "ISO 9797-1 method
       // 2 was used". Omitting it is a common source of chips rejecting DO'87'.
       parts.push(encodeTlv(DO87, concat(new Uint8Array([0x01]), encrypted)));
@@ -103,7 +110,11 @@ export class SecureMessagingSession {
     }
 
     const body = concat(...parts);
-    const mac = macWithPadding(this.p, this.keys.ksMac, concat(this.ssc, header, body));
+    const mac = this.suite.mac(
+      this.p,
+      this.keys.ksMac,
+      padToBlock(concat(this.ssc, header, body), block),
+    );
     const checksum = encodeTlv(DO8E, mac);
 
     const payload = concat(body, checksum);
@@ -140,7 +151,11 @@ export class SecureMessagingSession {
       this.ssc,
       ...objects.map((o) => encodeTlv(o.tag, o.value)),
     );
-    const expected = macWithPadding(this.p, this.keys.ksMac, macInput);
+    const expected = this.suite.mac(
+      this.p,
+      this.keys.ksMac,
+      padToBlock(macInput, this.suite.blockSize),
+    );
     if (!timingSafeEqual(expected, checksum.value)) {
       throw new SecureMessagingError('The response failed its integrity check.');
     }
@@ -161,12 +176,15 @@ export class SecureMessagingSession {
     // does not.
     const body =
       encrypted.tag === DO87 ? encrypted.value.subarray(1) : encrypted.value;
-    if (body.length === 0 || body.length % BLOCK_SIZE !== 0) {
+    if (body.length === 0 || body.length % this.suite.blockSize !== 0) {
       throw new SecureMessagingError('The response ciphertext was misaligned.');
     }
 
     return {
-      data: unpadFromBlock(decrypt3Des(this.p, this.keys.ksEnc, body), BLOCK_SIZE),
+      data: unpadFromBlock(
+        this.suite.decrypt(this.p, this.keys.ksEnc, body, this.ssc),
+        this.suite.blockSize,
+      ),
       statusWord,
     };
   }

package/src/emrtd/session.ts

@@ -3,6 +3,7 @@ import { buildBacChallenge, completeBac } from './bac';
 import { primitivesFromNative, type EmrtdPrimitives, type MrzKeyFields } from './crypto';
 import { EF, readFile, type Transceive } from './files';
 import { readOptionalFile } from './optionalRead';
+import { PaceError, PREFER_PACE, tryPace, type PaceOutcome } from './open';
 import { SecureMessagingSession } from './secureMessaging';
 import type { NfcReadStage } from './stages';
 
@@ -44,8 +45,15 @@ export interface EmrtdReadResult {
   sod?: string;
   /** DG2 — the portrait. Best-effort; the largest file and the likeliest to drop. */
   dg2?: string;
-  /** How the chip was unlocked. */
-  chipAuth: 'bac';
+  /** How the chip was unlocked. Reported to the server on the submission. */
+  chipAuth: 'bac' | 'pace';
+  /**
+   * Why the session is on that protocol, and the negotiated variant when PACE
+   * ran. Diagnostics only: it never changes the read, and it is what
+   * distinguishes "the chip does not speak PACE" from "our PACE failed".
+   */
+  paceOutcome?: PaceOutcome;
+  paceDetail?: string;
 }
 
 /** The raw transport, before secure messaging wraps it. */
@@ -137,23 +145,8 @@ export async function readChip(
   const p = primitivesFromNative(native);
 
   onStage?.('authenticating');
-  // SELECT + BAC are retried ONCE in place, on the same live connection.
-  // On Android the tag is routinely dispatched while the platform is still
-  // settling the link, so the first exchange dies with the chip right there —
-  // and an immediate second attempt succeeds with the phone untouched. The
-  // Flutter SDK documents and fixes this exact failure the same way
-  // (nfc_reader_emrtd.dart); a full session teardown cannot fix it, because
-  // Android never re-dispatches a tag that stayed in the field, so the outer
-  // retry loop just waited for a re-tap nobody knew to perform.
-  let sm: Awaited<ReturnType<typeof openSession>> | null = null;
-  for (let attempt = 0; sm === null; attempt += 1) {
-    try {
-      await selectApplication(native);
-      sm = await openSession(p, native, mrz);
-    } catch (err) {
-      if (attempt >= 1) throw err;
-    }
-  }
+  const access = await establishSession(p, native, mrz);
+  const sm = access.sm;
 
   const transceive: Transceive = async (command) => {
     const { data, statusWord } = await native.transceive(toBase64(command));
@@ -195,6 +188,117 @@ export async function readChip(
     dg1: toBase64(dg1),
     ...(sod ? { sod: toBase64(sod) } : {}),
     ...(dg2 ? { dg2: toBase64(dg2) } : {}),
-    chipAuth: 'bac',
+    chipAuth: access.chipAuth,
+    paceOutcome: access.outcome,
+    ...(access.detail ? { paceDetail: access.detail } : {}),
+  };
+}
+
+/**
+ * Open a secured session, trying both access protocols as needed.
+ *
+ * The ordering lives in open.ts (PREFER_PACE) along with why it is what it is.
+ * Whichever protocol goes first, the other still runs as the fallback, so a
+ * document that read before still reads.
+ */
+async function establishSession(
+  p: EmrtdPrimitives,
+  native: EmrtdTransport,
+  mrz: MrzKeyFields,
+): Promise<{
+  sm: SecureMessagingSession;
+  chipAuth: 'bac' | 'pace';
+  outcome: PaceOutcome;
+  detail?: string;
+}> {
+  // SELECT + BAC are retried ONCE in place, on the same live connection.
+  // On Android the tag is routinely dispatched while the platform is still
+  // settling the link, so the first exchange dies with the chip right there —
+  // and an immediate second attempt succeeds with the phone untouched. The
+  // Flutter SDK documents and fixes this exact failure the same way
+  // (nfc_reader_emrtd.dart); a full session teardown cannot fix it, because
+  // Android never re-dispatches a tag that stayed in the field, so the outer
+  // retry loop just waited for a re-tap nobody knew to perform.
+  const bac = async (): Promise<SecureMessagingSession> => {
+    let sm: SecureMessagingSession | null = null;
+    for (let attempt = 0; sm === null; attempt += 1) {
+      try {
+        await selectApplication(native);
+        sm = await openSession(p, native, mrz);
+      } catch (err) {
+        if (attempt >= 1) throw err;
+      }
+    }
+    return sm;
+  };
+
+  // PACE leaves the chip mid-protocol when it fails, so BAC after a failed
+  // PACE runs against a chip in an unknown state. Both orders below therefore
+  // re-SELECT the application first, which bac() already does.
+  const pace = async (): Promise<
+    { sm: SecureMessagingSession; detail: string } | { outcome: PaceOutcome; detail?: string }
+  > => {
+    try {
+      return await tryPace(p, native, mrz);
+    } catch (err) {
+      // A chip that fails PACE may still answer BAC, so this is never fatal
+      // by itself — only the reason is kept.
+      const detail =
+        err instanceof PaceError ? `${err.code}: ${err.message}` : String(err ?? '');
+      return { outcome: 'failed', detail };
+    }
   };
+
+  if (PREFER_PACE) {
+    const attempted = await pace();
+    if ('sm' in attempted) {
+      // After PACE the application must be selected through the secure channel.
+      await selectApplicationSecure(attempted.sm, native);
+      return { sm: attempted.sm, chipAuth: 'pace', outcome: 'used', detail: attempted.detail };
+    }
+    return { sm: await bac(), chipAuth: 'bac', outcome: attempted.outcome, detail: attempted.detail };
+  }
+
+  try {
+    return { sm: await bac(), chipAuth: 'bac', outcome: 'notAttempted' };
+  } catch (bacFailure) {
+    // BAC was refused. A chip that has retired it may still open with PACE, and
+    // trying costs one exchange against a document that has otherwise failed.
+    const attempted = await pace();
+    if ('sm' in attempted) {
+      await selectApplicationSecure(attempted.sm, native);
+      return { sm: attempted.sm, chipAuth: 'pace', outcome: 'used', detail: attempted.detail };
+    }
+    // Both refused. The BAC failure is the one the user is told about: its
+    // message already says the document details did not match.
+    throw bacFailure;
+  }
+}
+
+/**
+ * SELECT the eMRTD application through an established PACE channel.
+ *
+ * PACE authenticates at the Master File, so the application still has to be
+ * selected afterwards — and now every command is wrapped, so it goes through
+ * secure messaging rather than the raw transport.
+ */
+async function selectApplicationSecure(
+  sm: SecureMessagingSession,
+  transport: EmrtdTransport,
+): Promise<void> {
+  const wrapped = sm.protect({ cla: 0x00, ins: 0xa4, p1: 0x04, p2: 0x0c, data: AID });
+  const { data, statusWord } = await transport.transceive(toBase64(wrapped));
+  const body = fromBase64(data);
+  const framed = new Uint8Array(body.length + 2);
+  framed.set(body);
+  framed[body.length] = (statusWord >> 8) & 0xff;
+  framed[body.length + 1] = statusWord & 0xff;
+
+  const unwrapped = sm.unprotect(framed);
+  if (unwrapped.statusWord !== SW_OK) {
+    throw new EmrtdSessionError(
+      'The secured session did not hold when selecting the passport application.',
+      'select_failed',
+    );
+  }
 }

package/src/emrtd/suites.ts

@@ -0,0 +1,99 @@
+import { concat, padToBlock } from './bytes';
+import {
+  adjustParity,
+  decrypt3Des,
+  deriveDigestSha1,
+  encrypt3Des,
+  macWithPadding,
+  retailMac,
+  type EmrtdPrimitives,
+} from './crypto';
+
+// ---------------------------------------------------------------------------
+// Cipher suites (ICAO 9303 Part 11 §9.7 and §9.8).
+//
+// BAC always runs two-key 3DES with the ISO 9797-1 retail MAC. PACE negotiates:
+// it may use that same suite, or AES at 128, 192 or 256 bits with CMAC.
+//
+// They differ in more than the cipher, which is why this is one abstraction
+// rather than a flag:
+//
+//   • AES has a 16-byte block, so the padding unit AND the send-sequence
+//     counter are 16 bytes too.
+//   • AES derives a fresh IV per message by encrypting the counter, where 3DES
+//     uses a zero IV throughout.
+//   • AES-192/256 key derivation moves from SHA-1 to SHA-256, because SHA-1
+//     does not produce enough output.
+//   • The PACE authentication token pads for the retail MAC but must NOT be
+//     pre-padded for CMAC, which pads internally and takes a different branch
+//     for exact block multiples.
+//
+// Each of those, gotten wrong, produces a session that handshakes cleanly and
+// then fails on the first real command. So they are expressed here once.
+// ---------------------------------------------------------------------------
+
+export interface CipherSuite {
+  readonly name: string;
+  /** Cipher block size — also the padding unit and the SSC width. */
+  readonly blockSize: number;
+  /** Derived session-key length in bytes. */
+  readonly keyLength: number;
+  /** ICAO §9.7.1 key derivation: hash the secret with a 4-byte counter. */
+  deriveKey(p: EmrtdPrimitives, secret: Uint8Array, counter: number): Uint8Array;
+  /** `ssc` is present only for AES, which derives its IV from it. */
+  encrypt(p: EmrtdPrimitives, key: Uint8Array, padded: Uint8Array, ssc?: Uint8Array): Uint8Array;
+  decrypt(p: EmrtdPrimitives, key: Uint8Array, data: Uint8Array, ssc?: Uint8Array): Uint8Array;
+  /** MAC over data the caller has already padded. */
+  mac(p: EmrtdPrimitives, key: Uint8Array, data: Uint8Array): Uint8Array;
+  /** The PACE authentication token over an UNPADDED encoding. */
+  token(p: EmrtdPrimitives, key: Uint8Array, data: Uint8Array): Uint8Array;
+}
+
+/** Two-key 3DES with the retail MAC: what BAC always uses. */
+export const DES_EDE2_SUITE: CipherSuite = {
+  name: '3DES',
+  blockSize: 8,
+  keyLength: 16,
+  deriveKey: (p, secret, counter) =>
+    adjustParity(deriveDigestSha1(p, secret, counter).subarray(0, 16)),
+  encrypt: (p, key, padded) => encrypt3Des(p, key, padded),
+  decrypt: (p, key, data) => decrypt3Des(p, key, data),
+  mac: (p, key, data) => retailMac(p, key, data),
+  token: (p, key, data) => macWithPadding(p, key, data),
+};
+
+/** AES-CBC with CMAC, at 128, 192 or 256 bits. Only PACE reaches this. */
+export function aesSuite(keyLength: 16 | 24 | 32): CipherSuite {
+  return {
+    name: `AES-${keyLength * 8}`,
+    blockSize: 16,
+    keyLength,
+    deriveKey: (p, secret, counter) =>
+      // AES-128 keeps SHA-1; the longer keys need SHA-256 for enough output.
+      // No parity adjustment: that is a DES-only convention, and applying it to
+      // an AES key silently produces a different key.
+      keyLength === 16
+        ? deriveDigestSha1(p, secret, counter).subarray(0, 16)
+        : p.sha256(concat(secret, new Uint8Array([0, 0, 0, counter]))).subarray(0, keyLength),
+    encrypt: (p, key, padded, ssc) => p.aesCbc(key, padded, aesIv(p, key, ssc), true),
+    decrypt: (p, key, data, ssc) => p.aesCbc(key, data, aesIv(p, key, ssc), false),
+    // ICAO truncates the 16-byte CMAC to its leading 8 bytes.
+    mac: (p, key, data) => p.aesCmac(key, data).subarray(0, 8),
+    token: (p, key, data) => p.aesCmac(key, data).subarray(0, 8),
+  };
+}
+
+/**
+ * The per-message IV: AES encrypts the send-sequence counter with the session
+ * key, so two identical commands never produce identical ciphertext. A zero IV
+ * here (the 3DES convention) would leak that they were the same.
+ */
+function aesIv(p: EmrtdPrimitives, key: Uint8Array, ssc?: Uint8Array): Uint8Array {
+  if (!ssc) return new Uint8Array(16);
+  return p.aesCbc(key, ssc, new Uint8Array(16), true);
+}
+
+/** Pad for this suite's block size (ISO 9797-1 method 2). */
+export function padForSuite(suite: CipherSuite, data: Uint8Array): Uint8Array {
+  return padToBlock(data, suite.blockSize);
+}

package/src/index.ts

@@ -24,6 +24,7 @@ export type {
   KYCConsentContent,
   KYCSuccessContent,
   VoiceGuidanceConfig,
+  ProgressStyle,
   VoiceGuidanceOption,
   // Workflow-driven blocks — normally authored in the dashboard builder and
   // delivered by `workflowId`, but settable as props too.