@myazahq/kyc-sdk-react-native 2.0.1 → 2.1.0

package/README.md

@@ -1,8 +1,12 @@
 # @myazahq/kyc-sdk-react-native
 
-Myaza KYC SDK for **React Native (Expo)** — ID verification, document capture, and
-active **on-device** liveness. Mirrors the [web](https://www.npmjs.com/package/@myazahq/kyc-sdk-react)
-and Flutter SDKs feature-for-feature and calls the same Myaza KYC API server.
+Myaza KYC SDK for **React Native (Expo)** — ID verification with document
+auto-capture, **eMRTD chip reading (NFC)**, active **on-device** liveness,
+email/phone OTP verification, questionnaires, proof of address, and full
+business (**KYB**) verification, for any supported country. Mirrors the
+[web](https://www.npmjs.com/package/@myazahq/kyc-sdk-react) and Flutter SDKs
+feature-for-feature — including `workflowId` embeds — and calls the same Myaza
+KYC API server.
 
 The SDK is a **thin UI layer**: it captures the user's data (ID number, document
 photos, a live selfie), uploads the media, and submits a verification request.
@@ -157,7 +161,8 @@ export default function VerifyScreen() {
         title: "You're all set, {firstName}!",
         description: "We'll email you once your verification is reviewed.",
       }}
-      metadata={{ userId: 'test_user_123' }}
+      userId='usr_123'
+      metadata={{ orderId: 'ord_456' }}
       onStart={() => console.log('KYC started')}
       onStepChange={(step) => console.log('Step:', step)}
       onSubmit={(submission) => {
@@ -180,14 +185,28 @@ export default function VerifyScreen() {
 | Prop                    | Type                                      | Default             | Description                                                                                                          |
 | ----------------------- | ----------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | `apiKey`                | `string`                                  | —                   | **Required.** Sent as `Authorization: Bearer`. The **environment is derived from the key prefix** (`pk_test_…` → sandbox, `pk_live_…` → production); an unrecognized prefix throws. |
-| `country`               | `'NG' \| 'GH' \| 'KE' \| 'ZA' \| 'CI'`    | —                   | **Required.** Country whose ID types are offered.                                                                    |
+| `country`               | `string` (ISO-2)                          | —                   | Country whose ID types are offered. **Required unless `workflowId` is set** (the workflow carries its own country). Any ISO-2 code works — `'NG' \| 'GH' \| 'KE' \| 'ZA' \| 'CI'` keep autocomplete and client-side ID-number validation; other countries render their ID types from the server. |
+| `workflowId`            | `string` (`wf_…`)                         | —                   | Run a **published Workflow** built in the dashboard. Workflow config wins over overlapping props. See [Workflows](#workflows). |
+| `countries`             | `WorkflowCountry[]`                       | —                   | Multi-region — more than one entry inserts a country-select step between consent and ID type. Usually from a workflow. |
 | `idTypes`               | `IdType[]`                                | all allowed for org | Subset of ID types to offer; must be valid for `country`.                                                            |
+| `userId`                | `string`                                  | —                   | **Your** reference for the person being verified. Not matched during verification — it correlates repeat checks of the same user onto one identity so results map back to your record. Prefer this over putting a user id in `metadata`. |
 | `userData`              | `{ firstName?, lastName?, dateOfBirth? }` | —                   | Pre-fills the user's details.                                                                                        |
 | `enableSelfie`          | `boolean`                                 | `true`              | Capture a selfie during liveness.                                                                                    |
 | `enableDocumentCapture` | `boolean`                                 | `true`              | Enable the document-scan step for document IDs.                                                                      |
 | `allowDocumentUpload`   | `boolean`                                 | `true`              | Allow picking a document photo from the gallery as an alternative to the camera. `false` hides every "upload instead" affordance (it's still offered on the camera-permission-denied screen as an escape hatch). |
 | `enableLiveness`        | `boolean`                                 | `true`              | Run the liveness challenge step. The server can still disable it per ID type.                                        |
+| `livenessMode`          | `'gestures' \| 'flash' \| 'both'`         | `'gestures'`        | How liveness is proven. See [Liveness](#liveness).                                                                   |
+| `flashSequenceLength`   | `number` (2–5)                            | `4`                 | Colours in the flash sequence, for `'flash'` / `'both'`.                                                             |
 | `voiceGuidance`         | `boolean \| { enabled?, language? }`      | `true`              | Spoken liveness instructions (accessibility, TTS **output** — no microphone). `false` mutes it; pass `{ language: 'fr-FR' }` to set the voice. See [Robustness & error handling](#robustness--error-handling). |
+| `emailVerification`     | `EmailVerificationConfig`                 | off                 | Email OTP step after consent. See [Optional steps](#optional-steps).                                                 |
+| `phoneVerification`     | `PhoneVerificationConfig`                 | off                 | Phone OTP step (SMS or WhatsApp). See [Optional steps](#optional-steps).                                             |
+| `proofOfAddress`        | `ProofOfAddressConfig`                    | off                 | Proof-of-address upload after capture. See [Optional steps](#optional-steps).                                        |
+| `questionnaire`         | `QuestionnaireConfig`                     | off                 | Compliance declarations before submission. See [Optional steps](#optional-steps).                                    |
+| `nfc`                   | `NfcConfig`                               | off                 | **eMRTD chip read** — native on this SDK, and the strongest assurance level available. See [Optional steps](#optional-steps). |
+| `subjectType`           | `'individual' \| 'business'`              | `'individual'`      | Business (KYB) flows require a published KYB workflow. See [Business (KYB) flows](#business-kyb-flows).               |
+| `business`              | `WorkflowBusinessConfig`                  | —                   | KYB registry configuration. Normally supplied by a resolved workflow.                                                |
+| `deviceIntelligence`    | `boolean`                                 | `true`              | Device + IP fraud signals (multi-accounting, emulator, velocity). **Billed per verification**; `false` disables the analysis, its charge, and the SDK's fingerprint collection. |
+| `requireMobileDevice`   | `boolean`                                 | `false`             | Refuse to run on a desktop/laptop — relevant because React Native also targets desktop runtimes and emulators. The server re-checks and rejects with `mobile_device_required`. |
 | `showThemeToggle`       | `boolean`                                 | `true`              | Show a light/dark toggle inside the modal header. When `false`, the flow stays on `appearance.theme`.                |
 | `disableClose`          | `boolean`                                 | `false`             | Hide the close (X) and block **all** user dismissal (X, Android back, iOS swipe-down). The flow can then only be closed programmatically via `useMyazaKYC().close()`. |
 | `appearance`            | `KYCAppearance`                           | brand defaults      | Brand & theme the modal — colors, logo, light/dark. See [Appearance & theming](#appearance--theming).                |
@@ -209,11 +228,95 @@ base URL) from the API key prefix, the single source of truth:
 
 | Prefix     | Environment | Base URL                          |
 | ---------- | ----------- | --------------------------------- |
-| `pk_test_` | sandbox     | `https://sandbox.identity.myaza.app` |
-| `pk_live_` | production  | `https://identity.myaza.app`      |
+| `pk_test_` | sandbox     | `https://trust.myaza.app`      |
+| `pk_live_` | production  | `https://trust.myaza.app`      |
 
 An unrecognized or malformed key throws at setup (it never silently defaults).
 
+## Workflows
+
+Instead of configuring the flow in code, build it in the Myaza dashboard and
+reference it by id:
+
+```tsx
+<MyazaKYC apiKey="pk_live_xxx" workflowId="wf_abc123" userId="usr_123" />
+```
+
+- **Workflow config wins** over any overlapping prop — country, ID types, step
+  toggles, appearance, copy. Set them in the builder, not in code.
+- **Runtime data always comes from your code**: `userId`, `userData`,
+  `metadata`, and every callback.
+- `country` becomes optional, because the workflow carries it.
+
+This is the recommended way to drive the optional steps below: compliance teams
+change the flow in the dashboard without shipping a new app build — which
+matters far more on mobile than on web, where a redeploy is instant and an app
+store review is not.
+
+## Optional steps
+
+Steps that are off unless configured. Each is normally switched on in the
+dashboard workflow builder (so it rides `workflowId`), but every one can also be
+passed directly as a prop.
+
+The flow runs them in this order:
+
+```
+consent → email-verification → phone-verification → country-select → id-type
+       → id-input / document-capture → nfc → liveness → proof-of-address
+       → questionnaire → submitted
+```
+
+| Prop | Shape | What it adds |
+|---|---|---|
+| `emailVerification` | `{ enabled?, required?, codeLength?, maxAttempts?, inputStyle? }` | Email OTP right after consent. `required: false` adds a "skip for now". `codeLength` 4–8 (default 6), `maxAttempts` 1–5 (default 3). |
+| `phoneVerification` | same, plus `{ channels?, defaultCountry? }` | Phone OTP. `channels` defaults to `['sms']`; add `'whatsapp'` to offer it. |
+| `proofOfAddress` | `{ enabled?, documentTypes?, otherLabel?, maxAgeDays? }` | Upload a utility bill, bank statement, tenancy agreement, or other document. `maxAgeDays` is the recency window (default 90). |
+| `questionnaire` | `{ enabled?, title?, description?, fields }` | Compliance declarations before submission. Field `type` is one of `text`, `number`, `money`, `select`, `multiselect`, `boolean`, `date`. |
+| `nfc` | `{ enabled?, idTypes?, allowSkip? }` | Reads the passport/ID **chip** (eMRTD). |
+
+**The chip read is a real, native capability on this SDK** — unlike the web SDK,
+which cannot do ISO-DEP from a browser. It gives the strongest assurance level
+available. A device with no NFC radio skips the step automatically; `allowSkip`
+adds a manual escape hatch for a chip that will not read, revealed after a failed
+attempt rather than offered on arrival. Skipping never fails the verification —
+the chip result is a soft sub-result.
+
+Answers and outcomes arrive in the verification webhook
+(`data.questionnaire`, `data.emailVerification`, `data.phoneVerification`,
+`data.proofOfAddress`).
+
+```tsx
+<MyazaKYC
+  apiKey="pk_live_xxx"
+  country="NG"
+  nfc={{ enabled: true, allowSkip: true }}
+  phoneVerification={{ enabled: true, channels: ["sms", "whatsapp"] }}
+  questionnaire={{
+    title: "A few final questions",
+    fields: [
+      { key: "source_of_funds", label: "Source of funds", type: "select", required: true,
+        options: [{ value: "salary", label: "Salary" }, { value: "business", label: "Business income" }] },
+    ],
+  }}
+/>
+```
+
+## Business (KYB) flows
+
+When a resolved workflow's config carries `subjectType: 'business'`, the SDK runs
+a company-verification flow instead of the individual one: a registry lookup
+(country, product, registration number/name), and — when the workflow configures
+them — a company profile, directors & owners, and supporting-document uploads.
+
+KYB is **workflow-required**: there is no prop-only business flow, because the
+server rejects a business submission that does not reference a published KYB
+workflow.
+
+If the workflow asks the submitter to verify their own identity, the ordinary
+individual capture leg runs afterwards for them, and the success screen can hand
+back invite links for any directors or owners who need their own check.
+
 ## Trigger component & hook
 
 `<MyazaKYC />` renders a styled trigger that opens the modal. Beyond the config
@@ -411,7 +514,7 @@ and a short liveness video is recorded and uploaded best-effort.
 
 ## Documentation
 
-Full documentation, configuration options, and webhook setup: **[identity.myaza.co/documentation/sdks](https://identity.myaza.co/documentation/sdks)**.
+Full documentation, configuration options, and webhook setup: **[trust.myaza.co/documentation/sdks](https://trust.myaza.co/documentation/sdks)**.
 
 ## License
 

package/android/build.gradle

@@ -91,6 +91,10 @@ repositories {
 
 dependencies {
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+  // JPEG 2000 for the DG2 chip portrait — BitmapFactory cannot decode it and
+  // never will; JJ2000 is the pure-Java reference implementation. ~500KB.
+  implementation 'edu.ucar:jj2000:5.2'
   implementation 'com.facebook.react:react-android'
 
   // Nitro core — provides the HybridObject base + the NitroModules prefab the
@@ -107,4 +111,6 @@ dependencies {
 
   // Google ML Kit face detection — Android only. Same version as the Flutter SDK.
   implementation 'com.google.mlkit:face-detection:16.1.6'
+  // On-device text recognition, for reading the MRZ off a passport or ID card.
+  implementation 'com.google.mlkit:text-recognition:16.0.1'
 }

package/android/src/main/AndroidManifest.xml

@@ -1,12 +1,22 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
   <!--
-    The ML Kit face-detection model is downloaded on demand by Play Services.
-    This meta-data tells Play Services to fetch it at install time so the first
-    liveness session doesn't pay the download cost. Mirrors the Flutter SDK.
+    NFC, for reading a passport's eMRTD chip. `required="false"` on the feature
+    is deliberate: the rest of the SDK works without NFC, and marking it
+    required would hide the host app from every device that has no NFC radio.
+    The chip step checks availability at runtime and skips instead.
   -->
+  <uses-permission android:name="android.permission.NFC" />
+  <uses-feature android:name="android.hardware.nfc" android:required="false" />
+
   <application>
+    <!--
+      ML Kit models are downloaded on demand by Play Services. Naming them here
+      makes Play Services fetch them at INSTALL time, so the first liveness or
+      MRZ scan does not pay the download cost — which on a slow connection is
+      the difference between a step that works and one the user abandons.
+    -->
     <meta-data
       android:name="com.google.mlkit.vision.DEPENDENCIES"
-      android:value="face" />
+      android:value="face,ocr" />
   </application>
 </manifest>

package/android/src/main/java/com/margelo/nitro/myazakyc/HybridMyazaEmrtd.kt

@@ -0,0 +1,358 @@
+package com.margelo.nitro.myazakyc
+
+import android.app.Activity
+import android.nfc.NfcAdapter
+import android.os.Bundle
+import android.nfc.Tag
+import android.nfc.tech.IsoDep
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.util.Base64
+import java.io.ByteArrayOutputStream
+import com.facebook.react.bridge.ReactApplicationContext
+import com.margelo.nitro.NitroModules
+import com.margelo.nitro.core.Promise
+import java.security.SecureRandom
+import javax.crypto.Cipher
+import javax.crypto.spec.IvParameterSpec
+import javax.crypto.spec.SecretKeySpec
+import java.security.MessageDigest
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.TimeoutException
+
+/** How long to wait for the user to present a document before giving up. */
+private const val NFC_WAIT_SECONDS = 60L
+
+/**
+ * How long Android waits between "is the tag still there?" probes.
+ *
+ * Generous on purpose: the probes interleave with ISO-DEP traffic, and the
+ * default (~125ms) is a known cause of chips dropping partway through a large
+ * DG2 read. The read itself has its own timeout, so a tag genuinely removed is
+ * still noticed.
+ */
+private const val PRESENCE_CHECK_DELAY_MS = 5_000
+
+/**
+ * Android half of eMRTD chip reading, implementing the nitrogen-generated
+ * `HybridMyazaEmrtdSpec` from src/specs/MyazaEmrtd.nitro.ts. The iOS half is
+ * HybridMyazaEmrtd.swift.
+ *
+ * Two responsibilities, deliberately no more:
+ *
+ *  - TRANSPORT. `IsoDep` reader-mode, wrapped so TypeScript can send an APDU and
+ *    get bytes back. Everything above — BAC, secure messaging, file reads — is
+ *    TypeScript, tested against ICAO 9303's worked examples in CI.
+ *  - PRIMITIVES. javax.crypto's DES, AES and SHA. A hand-written DES in
+ *    JavaScript would be slower and a novel implementation on a path that
+ *    authenticates a passport.
+ *
+ * This file decides NOTHING about authenticity. It moves bytes.
+ */
+class HybridMyazaEmrtd : HybridMyazaEmrtdSpec() {
+
+  // @Volatile because every entry point runs on an ARBITRARY pool thread
+  // (Nitro's Promise.async dispatches to Dispatchers.Default) and the reader
+  // callback lands on a binder thread. Without it the `isoDep = dep` write in
+  // startSession has no happens-before edge to the read in transceive, and a
+  // fresh connection can be invisible to the very next call — the iOS side
+  // avoids this whole class by serializing on the main queue.
+  @Volatile private var isoDep: IsoDep? = null
+  @Volatile private var pending: CompletableFuture<Tag>? = null
+  @Volatile private var adapter: NfcAdapter? = null
+
+  private val context: ReactApplicationContext?
+    get() = NitroModules.applicationContext
+
+  // ── Transport ─────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this device can read chips.
+   *
+   * DELIBERATELY not the "sticky true" the iOS side uses. There, a false is
+   * always the platform lying about fixed hardware, so the first true is kept
+   * forever. Here `isEnabled` reports a SETTING the user can turn off mid-flow,
+   * so a false is real, actionable information and must be allowed to retract a
+   * previous true — telling someone their chip can be read when they have just
+   * disabled NFC would be worse than useless.
+   *
+   * Do not "harmonise" the two platforms: they are answering different
+   * questions.
+   */
+  override fun isAvailable(): Boolean {
+    val ctx = context ?: return false
+    return NfcAdapter.getDefaultAdapter(ctx)?.isEnabled == true
+  }
+
+  /**
+   * Decode an image format JS cannot render, returning base64 JPEG.
+   *
+   * Passport chips overwhelmingly store DG2 as JPEG 2000, which React Native
+   * cannot display. BitmapFactory handles the formats the platform knows —
+   * which does NOT include JPEG 2000 (an earlier comment here claimed it did;
+   * it never has, which is why the portrait showed on iOS and never on
+   * Android) — so JP2/J2K falls through to the bundled JJ2000 decoder.
+   *
+   * Empty string on failure rather than throwing: the preview is a courtesy and
+   * the chip read's verdict does not depend on it.
+   */
+  override fun decodeImage(dataBase64: String): Promise<String> {
+    return Promise.async {
+      try {
+        val bytes = Base64.decode(dataBase64, Base64.NO_WRAP)
+        val bitmap = BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
+          ?: Jp2Decoder.decode(bytes)
+          ?: return@async ""
+        val out = ByteArrayOutputStream()
+        bitmap.compress(Bitmap.CompressFormat.JPEG, 90, out)
+        Base64.encodeToString(out.toByteArray(), Base64.NO_WRAP)
+      } catch (_: Throwable) {
+        ""
+      }
+    }
+  }
+
+  override fun startSession(alertMessage: String): Promise<EmrtdTagInfo> {
+    // `alertMessage` is iOS's system NFC sheet; Android shows nothing of its
+    // own, so the SDK's own UI carries the instruction there.
+    return Promise.async {
+      val activity = context?.currentActivity
+        ?: throw IllegalStateException("No foreground activity to attach the NFC reader to.")
+      val nfc = NfcAdapter.getDefaultAdapter(activity)
+        ?: throw IllegalStateException("This device has no NFC hardware.")
+
+      val future = CompletableFuture<Tag>()
+      pending = future
+      adapter = nfc
+
+      // Reader mode with NFC-A/B and the platform's own NDEF check SKIPPED: a
+      // passport is not an NDEF tag, and letting the system probe for one adds
+      // a round trip and can knock the chip off the field.
+      //
+      // The presence-check delay is the setting that decides whether a large
+      // file survives. Android otherwise probes the tag every ~125ms to see if
+      // it is still there, and those probes interleave with an ISO-DEP exchange
+      // — long enough into a 30KB DG2 read, some chips drop the connection. The
+      // library the Flutter SDK uses sets this for the same reason.
+      val options = Bundle().apply {
+        putInt(NfcAdapter.EXTRA_READER_PRESENCE_CHECK_DELAY, PRESENCE_CHECK_DELAY_MS)
+      }
+      nfc.enableReaderMode(
+        activity,
+        { tag -> future.complete(tag) },
+        NfcAdapter.FLAG_READER_NFC_A or
+          NfcAdapter.FLAG_READER_NFC_B or
+          NfcAdapter.FLAG_READER_SKIP_NDEF_CHECK,
+        options,
+      )
+
+      // BOUNDED. `get()` with no timeout waits forever for a tap that may never
+      // come, and the caller would have no way out — the same unbounded-wait
+      // trap the SDK avoids everywhere else. A user who does not present a
+      // document gets a clean timeout instead of a frozen screen.
+      val tag = try {
+        future.get(NFC_WAIT_SECONDS, TimeUnit.SECONDS)
+      } catch (e: TimeoutException) {
+        throw IllegalStateException("No chip was detected. Try again and hold the phone still.")
+      }
+      val dep = IsoDep.get(tag)
+        ?: throw IllegalStateException("That tag does not speak ISO-DEP.")
+      // Passports are slow and DG2 is large; the default timeout aborts
+      // mid-file on a chip that is working perfectly well.
+      dep.timeout = 20_000
+      dep.connect()
+      isoDep = dep
+
+      EmrtdTagInfo(connected = true, uid = Base64.encodeToString(tag.id, Base64.NO_WRAP))
+    }
+  }
+
+  override fun stopSession(message: String): Promise<Unit> {
+    return Promise.async {
+      // Cancel a wait that is still in flight, so closing the sheet releases
+      // the caller rather than leaving it blocked until the timeout.
+      pending?.completeExceptionally(IllegalStateException("The scan was cancelled."))
+      runCatching { isoDep?.close() }
+      isoDep = null
+      pending = null
+      val activity = context?.currentActivity
+      if (activity != null) runCatching { adapter?.disableReaderMode(activity) }
+      adapter = null
+    }
+  }
+
+  override fun updateSessionMessage(message: String): Promise<Unit> {
+    // Android has no system NFC sheet to write to — the SDK's own screen
+    // narrates the read there. Accepted and ignored so the JS side can call
+    // one API on both platforms.
+    return Promise.async { }
+  }
+
+  override fun transceive(apduBase64: String): Promise<EmrtdApduResponse> {
+    return Promise.async {
+      val dep = isoDep ?: throw IllegalStateException("No chip is connected.")
+      val response = dep.transceive(Base64.decode(apduBase64, Base64.NO_WRAP))
+      if (response.size < 2) throw IllegalStateException("The chip returned a truncated response.")
+
+      // A non-success status word RESOLVES rather than throwing: 0x6CXX and
+      // 0x63CF are answers the protocol layer must interpret, not failures.
+      val sw1 = response[response.size - 2].toInt() and 0xFF
+      val sw2 = response[response.size - 1].toInt() and 0xFF
+      val data = response.copyOfRange(0, response.size - 2)
+
+      EmrtdApduResponse(
+        data = Base64.encodeToString(data, Base64.NO_WRAP),
+        statusWord = ((sw1 shl 8) or sw2).toDouble(),
+      )
+    }
+  }
+
+  // ── Primitives ────────────────────────────────────────────────────────────
+
+  override fun sha1(dataBase64: String): String = digest("SHA-1", dataBase64)
+
+  override fun sha256(dataBase64: String): String = digest("SHA-256", dataBase64)
+
+  private fun digest(algorithm: String, dataBase64: String): String =
+    Base64.encodeToString(
+      MessageDigest.getInstance(algorithm).digest(decode(dataBase64)),
+      Base64.NO_WRAP,
+    )
+
+  override fun desEde2Cbc(
+    keyBase64: String,
+    dataBase64: String,
+    ivBase64: String,
+    encrypt: Boolean,
+  ): String {
+    // Two-key 3DES is K1|K2|K1. javax.crypto's DESede wants all 24 bytes, so
+    // the expansion happens here rather than being assumed.
+    val key16 = decode(keyBase64)
+    require(key16.size == 16) { "3DES needs a 16-byte two-key value." }
+    val key24 = ByteArray(24)
+    System.arraycopy(key16, 0, key24, 0, 16)
+    System.arraycopy(key16, 0, key24, 16, 8)
+
+    val iv = decode(ivBase64)
+    // NoPadding: the protocol applies ISO 9797-1 method 2 itself, and letting
+    // the provider add PKCS#5 on top would corrupt every message.
+    return crypt(
+      "DESede/CBC/NoPadding",
+      SecretKeySpec(key24, "DESede"),
+      IvParameterSpec(if (iv.isEmpty()) ByteArray(8) else iv),
+      decode(dataBase64),
+      encrypt,
+    )
+  }
+
+  override fun desBlock(keyBase64: String, blockBase64: String, encrypt: Boolean): String =
+    // ECB on a single block — the retail MAC's inner primitive. The chaining is
+    // done in TypeScript, where the standard's construction is testable.
+    crypt(
+      "DES/ECB/NoPadding",
+      SecretKeySpec(decode(keyBase64), "DES"),
+      null,
+      decode(blockBase64),
+      encrypt,
+    )
+
+  override fun aesCbc(
+    keyBase64: String,
+    dataBase64: String,
+    ivBase64: String,
+    encrypt: Boolean,
+  ): String {
+    val iv = decode(ivBase64)
+    return crypt(
+      "AES/CBC/NoPadding",
+      SecretKeySpec(decode(keyBase64), "AES"),
+      IvParameterSpec(if (iv.isEmpty()) ByteArray(16) else iv),
+      decode(dataBase64),
+      encrypt,
+    )
+  }
+
+  override fun aesCmac(keyBase64: String, dataBase64: String): String {
+    // No CMAC in the platform providers, so RFC 4493 is built on AES-ECB here.
+    // A short, exactly-specified construction; the alternative is a
+    // third-party dependency inside the passport path.
+    val key = SecretKeySpec(decode(keyBase64), "AES")
+    val message = decode(dataBase64)
+    val block = 16
+
+    val l = decode(crypt("AES/ECB/NoPadding", key, null, ByteArray(block), true))
+    val k1 = shiftLeftXor(l)
+    val k2 = shiftLeftXor(k1)
+
+    val blocks = mutableListOf<ByteArray>()
+    var i = 0
+    while (i < message.size) {
+      blocks.add(message.copyOfRange(i, minOf(i + block, message.size)))
+      i += block
+    }
+    if (blocks.isEmpty()) blocks.add(ByteArray(0))
+
+    // The final block is XORed with K1 when the message divides evenly, and
+    // padded then XORed with K2 when it does not.
+    var last = blocks.removeAt(blocks.size - 1)
+    last = if (last.size == block) {
+      xor(last, k1)
+    } else {
+      val padded = ByteArray(block)
+      System.arraycopy(last, 0, padded, 0, last.size)
+      padded[last.size] = 0x80.toByte()
+      xor(padded, k2)
+    }
+
+    var chain = ByteArray(block)
+    for (b in blocks + listOf(last)) {
+      chain = decode(crypt("AES/ECB/NoPadding", key, null, xor(chain, b), true))
+    }
+    return Base64.encodeToString(chain, Base64.NO_WRAP)
+  }
+
+  override fun randomBytes(length: Double): String {
+    val bytes = ByteArray(length.toInt())
+    // SecureRandom, not Random: the BAC nonce's unpredictability is what stops
+    // the exchange being replayable.
+    SecureRandom().nextBytes(bytes)
+    return Base64.encodeToString(bytes, Base64.NO_WRAP)
+  }
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+
+  private fun decode(b64: String): ByteArray =
+    if (b64.isEmpty()) ByteArray(0) else Base64.decode(b64, Base64.NO_WRAP)
+
+  private fun xor(a: ByteArray, b: ByteArray): ByteArray =
+    ByteArray(minOf(a.size, b.size)) { (a[it].toInt() xor b[it].toInt()).toByte() }
+
+  /** One-bit left shift, XORed with the RFC 4493 constant on overflow. */
+  private fun shiftLeftXor(input: ByteArray): ByteArray {
+    val out = ByteArray(input.size)
+    var carry = 0
+    for (i in input.indices.reversed()) {
+      val byte = input[i].toInt() and 0xFF
+      out[i] = ((byte shl 1) or carry).toByte()
+      carry = if (byte and 0x80 != 0) 1 else 0
+    }
+    if (input[0].toInt() and 0x80 != 0) {
+      out[out.size - 1] = (out[out.size - 1].toInt() xor 0x87).toByte()
+    }
+    return out
+  }
+
+  private fun crypt(
+    transformation: String,
+    key: SecretKeySpec,
+    iv: IvParameterSpec?,
+    data: ByteArray,
+    encrypt: Boolean,
+  ): String {
+    val cipher = Cipher.getInstance(transformation)
+    val mode = if (encrypt) Cipher.ENCRYPT_MODE else Cipher.DECRYPT_MODE
+    if (iv == null) cipher.init(mode, key) else cipher.init(mode, key, iv)
+    return Base64.encodeToString(cipher.doFinal(data), Base64.NO_WRAP)
+  }
+}