ciesign-react-native 0.1.0 → 0.3.0

package/README.md

@@ -66,10 +66,10 @@ Inputs and outputs are `Uint8Array`. The promise stays pending until the card is
 
 | Export | |
 |---|---|
-| `cieSession(pin, use, { prompt?, error?, savePin?, biometricPrompt?, biometricCancel? })` | Waits for the card and verifies the PIN, then resolves to what `use({ certificate, sign })` resolves to. The NFC session ends when `use` settles: the card must stay on the phone until then. `pin` is the 8-digit PIN or `SAVED_PIN`. `prompt` and `error` are the iOS NFC sheet texts; the others are explained under [Saved PIN](#saved-pin). |
+| `cieSession(pin, use, { prompt?, error?, messages?, onStep?, savePin?, biometricPrompt?, biometricCancel?, useSavedCertificate?, beforeCard? })` | Waits for the card and verifies the PIN, then resolves to what `use({ certificate, sign })` resolves to. The NFC session ends when `use` settles: the card must stay on the phone until then. `pin` is the 8-digit PIN or `SAVED_PIN`. `prompt` and `error` are the iOS NFC sheet texts while waiting for the card and on failure; `messages` and `onStep` are explained under [Progress](#progress), the others under [Saved PIN](#saved-pin). |
 | `certificate` | The card's DER authentication certificate: holder name and fiscal code are in its subject. |
 | `sign(digestInfo)` | RSA PKCS#1 v1.5 signature (the card adds the padding) of a DER DigestInfo, checked against `certificate`. Call it as often as needed while `use` runs; calls run one at a time, in order. |
-| `SAVED_PIN`, `pinStatus()`, `forgetPin()` | See [Saved PIN](#saved-pin). |
+| `SAVED_PIN`, `pinStatus()`, `forgetPin()`, `savedCertificate()` | See [Saved PIN](#saved-pin). |
 | `cancel()` | Aborts the session in progress. Android has no system NFC sheet, so give users a cancel button. |
 
 iOS ends an NFC session 60 seconds after it starts, `use` included: prepare what does not depend on the certificate, such as a PDF's byte range, before calling `cieSession`.
@@ -93,6 +93,27 @@ A PIN that is not 8 digits throws a plain `Error`. Card errors carry a `code`:
 
 On Android the app must stay in the foreground while the card is read.
 
+### Progress
+
+A session goes through these steps. On iOS the NFC sheet shows the text of each one; `messages` overrides any of them. `onStep(step)` is called as each one is reached, for example to show progress in your own UI on Android, which has no NFC sheet.
+
+| Step | When | Default iOS sheet text |
+|---|---|---|
+| `detected` | The card is on the phone. | CIE rilevata, non allontanarla |
+| `pin` | The PIN is being verified. | Verifica del PIN… |
+| `ready` | PIN verified and certificate read, or taken from the saved one: `use` starts. | PIN verificato |
+| `signing` | A signature starts, once per `sign`. | Firma in corso… |
+| `done` | `use` resolved and the session is over. The sheet shows it next to its checkmark. | Operazione completata |
+
+```ts
+const signatures = await cieSession(pin, use, {
+  messages: { done: 'Verbale firmato' },
+  onStep: (step) => setStatus(step),
+});
+```
+
+Steps only move forward. A failed session stops at the last step it reached and rejects; on iOS the sheet shows `error`.
+
 ### Saved PIN
 
 Optional: apps that always pass the PIN don't need any of this. With `savePin`, the typed PIN is saved once the card accepts it. Later operations pass `SAVED_PIN`, which asks for Face ID, Touch ID or a fingerprint instead of the PIN.
@@ -117,9 +138,27 @@ const signatures =
 - **Native only.** A saved PIN is decrypted in native code and sent to the card; it never reaches JavaScript.
 - One PIN per app: saving again replaces it. `forgetPin()` deletes it. `savePin` fails with `BIOMETRIC_UNAVAILABLE` before the card is read when `pinStatus()` is `'unavailable'`.
 
+#### Saved certificate
+
+The card certificate is saved with the PIN: on iOS in a Keychain item of its own, readable while the device is unlocked, never synced or backed up; on Android next to the encrypted PIN in `noBackupFilesDir`. It is public (it goes into every signature), so no biometric guards it. It is replaced and deleted with the PIN; a `SAVED_PIN` session that reads the certificate from the card saves it too, for PINs saved before it was.
+
+`savedCertificate()` returns it without any UI, or `null`. Knowing it before the card is on the phone lets you prepare what to sign before the NFC session, which iOS ends after 60 seconds. Then `useSavedCertificate: true` makes the `SAVED_PIN` session skip reading it: the card is still checked by its NIS (`WRONG_CARD` otherwise) and every signature against the certificate. Without the option, or without a saved certificate, the session reads it from the card as usual.
+
+To prepare it after the biometric prompt rather than before, pass `beforeCard`: with `SAVED_PIN`, the session calls it once the prompt has unlocked the PIN, with the saved certificate it will use (or `null`), and waits for it before the NFC session starts. A user who cancels the prompt never reaches your server, and the wait doesn't count toward iOS's 60 seconds. If it throws, the session ends with that error and the card is never read.
+
+```ts
+let prepared: Prepared | null = null;
+const signatures = await cieSession(SAVED_PIN, async (cie) => sign(prepared ?? (await prepare(cie.certificate)), cie), {
+  useSavedCertificate: true,
+  beforeCard: async (certificate) => {
+    if (certificate) prepared = await prepare(certificate); // e.g. your server's hashes to sign
+  },
+});
+```
+
 ## How it works
 
-`cieSession` opens one NFC session: NIS read (EF 1001), secure messaging (Diffie-Hellman and device authentication), PIN verification, certificate read (EF 1003). Each `sign` then sends `MSE SET` (key `0x81`, RSA PKCS#1) and `INTERNAL AUTHENTICATE` with the DigestInfo over the same secure channel.
+`cieSession` opens one NFC session: NIS read (EF 1001), secure messaging (Diffie-Hellman and device authentication), PIN verification, certificate read (EF 1003, skipped with `useSavedCertificate`). Each `sign` then sends `MSE SET` (key `0x81`, RSA PKCS#1) and `INTERNAL AUTHENTICATE` with the DigestInfo over the same secure channel.
 
 - Android drives `CieCommands` from PagoPA's [`cie-sdk-android`](https://github.com/pagopa/cie-sdk-android) through a Java shim, because the class is Kotlin-internal. The dependency is pinned to `0.1.11`: check the shim before upgrading.
 - iOS implements the same protocol in `ios/CieCard.swift`, derived from PagoPA's [`cie-sdk-ios`](https://github.com/pagopa/cie-sdk-ios), whose signing code is not public.

package/android/src/main/java/it/codingduck/ciesign/CieCard.java

@@ -17,9 +17,13 @@ final class CieCard {
     return commands.getServiceID();
   }
 
-  /** Opens secure messaging, verifies the PIN and returns the certificate file (EF 1003, zero padded). */
-  byte[] open(String pin) throws Exception {
+  /** Opens secure messaging and verifies the PIN. */
+  void open(String pin) throws Exception {
     commands.startSecureChannel(pin);
+  }
+
+  /** The certificate file (EF 1003, zero padded), once {@link #open} has verified the PIN. */
+  byte[] certificate() throws Exception {
     return commands.readCertCie();
   }
 

package/android/src/main/java/it/codingduck/ciesign/CieSignModule.kt

@@ -28,40 +28,62 @@ class CieSignModule : Module() {
   private var tag: IsoDep? = null
   private var card: CieCard? = null
   private var prompt: BiometricPrompt? = null
+  private var unlocked: Unlocked? = null
   private val savedPin by lazy { SavedPin(requireNotNull(appContext.reactContext)) }
 
   override fun definition() = ModuleDefinition {
     Name("CieSign")
 
-    // A null `pin` unlocks the saved one; `save` saves `pin` once the card accepts it. Both show the biometric prompt first.
-    AsyncFunction("connect") { id: Int, pin: String?, save: Boolean, _: String, biometricPrompt: String, biometricCancel: String, promise: Promise ->
+    Events("onStep")
+
+    // Unlocks the saved PIN for `connect` behind the biometric prompt. With `useSavedCertificate`, resolves to the
+    // certificate saved with it when it is of the same card, which `connect` then returns instead of reading it.
+    AsyncFunction("unlock") { id: Int, biometricPrompt: String, biometricCancel: String, useSavedCertificate: Boolean, promise: Promise ->
+      val activity = appContext.currentActivity ?: throw CodedException("NFC_UNAVAILABLE", "No foreground activity", null)
+      if (NfcAdapter.getDefaultAdapter(activity)?.isEnabled != true) throw CodedException("NFC_UNAVAILABLE", "NFC is missing or turned off", null)
+      start(id, promise)
+      try {
+        val saved = savedPin.saved() ?: throw CodedException("PIN_NOT_SAVED", "No saved PIN", null)
+        authenticate(activity, id, saved.cipher, biometricPrompt, biometricCancel) {
+          val pin = try {
+            String(it.doFinal(saved.pin))
+          } catch (e: Exception) {
+            savedPin.delete()
+            throw CodedException("PIN_NOT_SAVED", "The saved PIN cannot be decrypted", e)
+          }
+          val certificate = if (useSavedCertificate) savedPin.certificate(saved.card) else null
+          val waiting = synchronized(lock) { take(id)?.also { unlocked = Unlocked(pin, saved.card, certificate) } }
+          waiting?.resolve(certificate)
+        }
+      } catch (e: Exception) {
+        take(id)?.reject(coded(e))
+      }
+    }
+
+    // A null `pin` continues the session `unlock` started; `save` saves `pin` once the card accepts it, after the biometric
+    // prompt. The messages are for the iOS NFC sheet: Android has none.
+    AsyncFunction("connect") { id: Int, pin: String?, save: Boolean, _: Map<String, String>, biometricPrompt: String, biometricCancel: String, promise: Promise ->
       val activity = appContext.currentActivity ?: throw CodedException("NFC_UNAVAILABLE", "No foreground activity", null)
       val adapter = NfcAdapter.getDefaultAdapter(activity)
       if (adapter?.isEnabled != true) throw CodedException("NFC_UNAVAILABLE", "NFC is missing or turned off", null)
-      synchronized(lock) {
-        if (id <= closed) throw cancelled()
-        end()
-        session = id
-        pending = promise
+      val saved = if (pin == null) {
+        synchronized(lock) {
+          if (id <= closed || session != id) throw cancelled()
+          val found = unlocked ?: throw CodedException("PIN_NOT_SAVED", "The saved PIN was not unlocked", null)
+          pending = promise
+          found
+        }
+      } else {
+        start(id, promise)
+        null
       }
       try {
         when {
-          pin == null -> {
-            val saved = savedPin.saved() ?: throw CodedException("PIN_NOT_SAVED", "No saved PIN", null)
-            authenticate(activity, id, saved.cipher, biometricPrompt, biometricCancel) {
-              val unlocked = try {
-                String(it.doFinal(saved.pin))
-              } catch (e: Exception) {
-                savedPin.delete()
-                throw CodedException("PIN_NOT_SAVED", "The saved PIN cannot be decrypted", e)
-              }
-              read(activity, adapter, id, unlocked, saved.card, null)
-            }
-          }
+          saved != null -> read(activity, adapter, id, saved.pin, saved.card, null, saved.certificate)
           save -> authenticate(activity, id, savedPin.encrypter(), biometricPrompt, biometricCancel) {
-            read(activity, adapter, id, pin, null, savedPin.seal(it, pin))
+            read(activity, adapter, id, requireNotNull(pin), null, savedPin.seal(it, requireNotNull(pin)), null)
           }
-          else -> read(activity, adapter, id, pin, null, null)
+          else -> read(activity, adapter, id, requireNotNull(pin), null, null, null)
         }
       } catch (e: Exception) {
         take(id)?.reject(coded(e))
@@ -77,7 +99,7 @@ class CieSignModule : Module() {
       }
     }
 
-    Function("close") { id: Int, _: String? ->
+    Function("close") { id: Int, _: String?, _: String? ->
       synchronized(lock) {
         closed = maxOf(closed, id)
         if (session in 1..id) end()
@@ -88,16 +110,29 @@ class CieSignModule : Module() {
 
     AsyncFunction("forgetPin") { savedPin.delete() }
 
+    AsyncFunction("savedCertificate") { savedPin.certificate() }
+
     OnDestroy { synchronized(lock) { end() } }
   }
 
+  /** Ends any other session and makes `id` the current one, settled by `promise`. */
+  private fun start(id: Int, promise: Promise) = synchronized(lock) {
+    if (id <= closed) throw cancelled()
+    end()
+    session = id
+    pending = promise
+  }
+
   private fun take(id: Int): Promise? = synchronized(lock) { pending.takeIf { session == id }.also { if (it != null) pending = null } }
 
-  /** `owner`: NIS the saved PIN belongs to; `sealed`: encrypted PIN to save once the card accepts it. */
-  private fun read(activity: Activity, adapter: NfcAdapter, id: Int, pin: String, owner: String?, sealed: String?) {
+  /**
+   * `owner`: NIS the saved PIN belongs to; `sealed`: encrypted PIN to save once the card accepts it; `saved`: that card's
+   * certificate file, returned instead of reading it.
+   */
+  private fun read(activity: Activity, adapter: NfcAdapter, id: Int, pin: String, owner: String?, sealed: String?, saved: ByteArray?) {
     val flags = NfcAdapter.FLAG_READER_NFC_A or NfcAdapter.FLAG_READER_NFC_B or NfcAdapter.FLAG_READER_SKIP_NDEF_CHECK
     synchronized(lock) {
-      if (session == id) adapter.enableReaderMode(activity, { onTag(it, id, pin, owner, sealed) }, flags, null)
+      if (session == id) adapter.enableReaderMode(activity, { onTag(it, id, pin, owner, sealed, saved) }, flags, null)
     }
   }
 
@@ -130,7 +165,7 @@ class CieSignModule : Module() {
   }
 
   // Runs on the NFC thread; the tag stays connected after returning, until the session ends.
-  private fun onTag(discovered: Tag, id: Int, pin: String, owner: String?, sealed: String?) {
+  private fun onTag(discovered: Tag, id: Int, pin: String, owner: String?, sealed: String?, saved: ByteArray?) {
     val promise = take(id) ?: return
     var pinStatus = 0
     try {
@@ -144,6 +179,7 @@ class CieSignModule : Module() {
         }
         tag = isoDep
       }
+      step(id, "detected")
       val c = CieCard(object : OnTransmit {
         override fun sendCommand(apdu: ByteArray, nfcEvents: NfcEvent): ApduResponse {
           val response = isoDep.transceive(apdu)
@@ -155,8 +191,10 @@ class CieSignModule : Module() {
       })
       val nis = c.serviceId()
       if (owner != null && owner != nis) throw CodedException("WRONG_CARD", "Not the card the PIN was saved for", null)
-      val certificate = c.open(pin)
+      step(id, "pin")
+      c.open(pin)
       if (sealed != null) savedPin.store(nis, sealed)
+      val certificate = saved ?: c.certificate().also { if (sealed != null || owner != null) savedPin.storeCertificate(nis, it) }
       synchronized(lock) {
         if (session != id) throw cancelled()
         card = c
@@ -169,11 +207,14 @@ class CieSignModule : Module() {
     }
   }
 
+  private fun step(id: Int, step: String) = sendEvent("onStep", mapOf("id" to id, "step" to step))
+
   private fun end() {
     pending?.reject(cancelled())
     pending = null
     prompt?.let { appContext.currentActivity?.runOnUiThread(it::cancelAuthentication) }
     prompt = null
+    unlocked = null
     card = null
     runCatching { tag?.close() }
     tag = null
@@ -181,6 +222,9 @@ class CieSignModule : Module() {
     appContext.currentActivity?.let { NfcAdapter.getDefaultAdapter(it)?.disableReaderMode(it) }
   }
 
+  /** The saved PIN `unlock` decrypted, its card's NIS and, when asked for, that card's saved certificate. */
+  private class Unlocked(val pin: String, val card: String, val certificate: ByteArray?)
+
   private fun cancelled() = CodedException("CANCELLED", "Cancelled", null)
 
   // Under secure messaging the card's status word is in DO 99, ahead of the MAC; otherwise it ends the response.

package/android/src/main/java/it/codingduck/ciesign/SavedPin.kt

@@ -22,12 +22,14 @@ import javax.crypto.spec.GCMParameterSpec
 /**
  * The CIE PIN encrypted with an AES-GCM Keystore key, in StrongBox when the device has it and otherwise in the TEE. The key
  * encrypts and decrypts only right after a strong biometric matches one enrolled when it was made. The file is not backed up.
+ * Next to it, its card's certificate: public, so stored as is, and replaced or deleted with the PIN.
  */
 internal class SavedPin(private val context: Context) {
   /** The encrypted PIN, the NIS of its card and the decrypt cipher that a biometric unlocks. */
   class Saved(val card: String, val pin: ByteArray, val cipher: Cipher)
 
   private val file = File(context.noBackupFilesDir, "ciesign-pin")
+  private val certificateFile = File(context.noBackupFilesDir, "ciesign-certificate")
   private val keyStore = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
 
   val canSave get() = BiometricManager.from(context).canAuthenticate(BIOMETRIC_STRONG) == BiometricManager.BIOMETRIC_SUCCESS
@@ -61,10 +63,24 @@ internal class SavedPin(private val context: Context) {
     }
 
   /** Replaces the saved PIN; `card` is the NIS of the card that accepted it. */
-  fun store(card: String, sealed: String) = file.writeText("$card\n$sealed")
+  fun store(card: String, sealed: String) {
+    certificateFile.delete()
+    file.writeText("$card\n$sealed")
+  }
+
+  /** Saves the certificate file of the card whose PIN is saved; `card` is its NIS. */
+  fun storeCertificate(card: String, certificate: ByteArray) = certificateFile.writeText("$card\n${encode(certificate)}")
+
+  /** The certificate file saved with the PIN, if it is the card with NIS `card` (any when null); null when none is saved. */
+  fun certificate(card: String? = null): ByteArray? {
+    if (!file.exists()) return null
+    val (owner, certificate) = runCatching { certificateFile.readLines() }.getOrNull()?.takeIf { it.size == 2 } ?: return null
+    return if (card == null || card == owner) Base64.decode(certificate, Base64.NO_WRAP) else null
+  }
 
   fun delete() {
     file.delete()
+    certificateFile.delete()
   }
 
   private fun cipher(mode: Int, iv: ByteArray? = null): Cipher? {

package/build/index.d.ts

@@ -6,16 +6,32 @@ export declare const SAVED_PIN: unique symbol;
 /** The full 8-digit PIN, or `SAVED_PIN`. */
 export type Pin = string | typeof SAVED_PIN;
 /**
- * `prompt`, `error`: texts of the iOS NFC sheet. `savePin`: once the card accepts the PIN, save it for `SAVED_PIN`.
- * `biometricPrompt`, `biometricCancel`: texts of the biometric prompt shown before the card is read, wherever the secure
- * hardware requires one: `SAVED_PIN` everywhere, `savePin` on Android only.
+ * Progress of a session, in order: `detected` the card is on the phone; `pin` the PIN is being verified; `ready` the PIN
+ * is verified and the certificate read (or taken from the saved one), `use` starts; `signing` a signature starts, once
+ * per `sign`; `done` `use` resolved and the session is over.
+ */
+export type CieStep = 'detected' | 'pin' | 'ready' | 'signing' | 'done';
+/**
+ * `prompt`, `error`: texts of the iOS NFC sheet while it waits for the card and when the session fails; `messages`: its
+ * text at each step. `onStep`: called at each step, e.g. to show progress on Android, which has no NFC sheet.
+ * `savePin`: once the card accepts the PIN, save it for `SAVED_PIN`, with the card certificate. `biometricPrompt`,
+ * `biometricCancel`: texts of the biometric prompt shown before the card is read, wherever the secure hardware requires
+ * one: `SAVED_PIN` everywhere, `savePin` on Android only. `useSavedCertificate`: with `SAVED_PIN`, skip reading the
+ * certificate from the card and use the one saved with the PIN (see `savedCertificate`), when there is one.
+ * `beforeCard`: with `SAVED_PIN`, runs once the biometric prompt has unlocked the PIN and before the NFC session waits for
+ * the card, with the saved certificate the session will use (`useSavedCertificate`), or null: the session waits for it, so
+ * what to sign can be prepared after the prompt and outside iOS's 60-second NFC limit.
  */
 export type CieOptions = {
     prompt?: string;
     error?: string;
+    messages?: Partial<Record<CieStep, string>>;
+    onStep?: (step: CieStep) => void;
     savePin?: boolean;
     biometricPrompt?: string;
     biometricCancel?: string;
+    useSavedCertificate?: boolean;
+    beforeCard?: (savedCertificate: Bytes | null) => Promise<void>;
 };
 /** A card whose PIN has been verified, for as long as `use` runs. */
 export type CieSession = {
@@ -33,5 +49,11 @@ export declare function cieSession<T>(pin: Pin, use: (session: CieSession) => Pr
 export declare const cancel: () => void;
 /** Whether a PIN is saved, without showing any UI. */
 export declare const pinStatus: () => Promise<PinStatus>;
-/** Deletes the saved PIN. */
+/** Deletes the saved PIN and its certificate. */
 export declare const forgetPin: () => Promise<void>;
+/**
+ * The DER certificate of the card whose PIN is saved, without any UI: known before the card is on the phone, e.g. to
+ * prepare what to sign before a `SAVED_PIN` session with `useSavedCertificate`. Null when no PIN is saved, or none was
+ * saved with it yet: a `SAVED_PIN` session that reads the certificate from the card saves it.
+ */
+export declare function savedCertificate(): Promise<Bytes | null>;

package/build/index.js

@@ -2,6 +2,14 @@ import { trimDer, verify } from './certificate';
 import Native, {} from './native';
 /** Pass instead of the PIN to use the one saved with `savePin`, unlocked with Face ID, Touch ID or a fingerprint. */
 export const SAVED_PIN = Symbol('SAVED_PIN');
+const STEPS = ['detected', 'pin', 'ready', 'signing', 'done'];
+const MESSAGES = {
+    detected: 'CIE rilevata, non allontanarla',
+    pin: 'Verifica del PIN…',
+    ready: 'PIN verificato',
+    signing: 'Firma in corso…',
+    done: 'Operazione completata',
+};
 let session = 0; // id of the latest NFC session
 /**
  * Waits for the card and verifies the PIN, then runs `use`: every `sign` goes through this NFC session, which ends when
@@ -10,15 +18,33 @@ let session = 0; // id of the latest NFC session
 export async function cieSession(pin, use, options = {}) {
     if (pin !== SAVED_PIN && !/^\d{8}$/.test(pin))
         throw new Error('The CIE PIN has 8 digits');
-    const { prompt = "Avvicina la CIE al retro dell'iPhone", error = 'Operazione non riuscita', savePin = false, biometricPrompt = pin === SAVED_PIN ? 'Sblocca il PIN della CIE' : 'Salva il PIN della CIE', biometricCancel = 'Annulla', } = options;
+    const { prompt = "Avvicina la CIE al retro dell'iPhone", error = 'Operazione non riuscita', savePin = false, biometricPrompt = pin === SAVED_PIN ? 'Sblocca il PIN della CIE' : 'Salva il PIN della CIE', biometricCancel = 'Annulla', useSavedCertificate = false, onStep, beforeCard, } = options;
+    const message = (s) => options.messages?.[s] ?? MESSAGES[s];
     const id = ++session;
     let done = false;
+    // Native events can arrive after `ready`: steps only move forward, except one `signing` per signature.
+    let reached = -1;
+    const step = (s) => {
+        const i = STEPS.indexOf(s);
+        if (i < reached || (i === reached && s !== 'signing'))
+            return;
+        reached = i;
+        onStep?.(s);
+    };
+    const subscription = onStep && Native.addListener('onStep', (event) => event.id === id && step(event.step));
     try {
-        const certificate = trimDer(await Native.connect(id, pin === SAVED_PIN ? null : pin, savePin, prompt, biometricPrompt, biometricCancel));
+        const sheet = { prompt, detected: message('detected'), pin: message('pin'), ready: message('ready'), signing: message('signing') };
+        if (pin === SAVED_PIN) {
+            const saved = await Native.unlock(id, biometricPrompt, biometricCancel, useSavedCertificate);
+            await beforeCard?.(saved && trimDer(saved));
+        }
+        const certificate = trimDer(await Native.connect(id, pin === SAVED_PIN ? null : pin, savePin, sheet, biometricPrompt, biometricCancel));
+        step('ready');
         let last = Promise.resolve();
         const sign = (digestInfo) => {
             const input = digestInfo.slice(); // signed later, once the calls before it finish
             const signature = last.then(async () => {
+                step('signing');
                 const signature = await Native.sign(id, input);
                 verify(certificate, input, signature);
                 return signature;
@@ -31,12 +57,24 @@ export async function cieSession(pin, use, options = {}) {
         return result;
     }
     finally {
-        Native.close(id, done ? null : error);
+        subscription?.remove();
+        Native.close(id, done ? null : error, done ? message('done') : null);
+        if (done)
+            step('done');
     }
 }
 /** Aborts the CIE session in progress. */
-export const cancel = () => Native.close(session, null);
+export const cancel = () => Native.close(session, null, null);
 /** Whether a PIN is saved, without showing any UI. */
 export const pinStatus = () => Native.pinStatus();
-/** Deletes the saved PIN. */
+/** Deletes the saved PIN and its certificate. */
 export const forgetPin = () => Native.forgetPin();
+/**
+ * The DER certificate of the card whose PIN is saved, without any UI: known before the card is on the phone, e.g. to
+ * prepare what to sign before a `SAVED_PIN` session with `useSavedCertificate`. Null when no PIN is saved, or none was
+ * saved with it yet: a `SAVED_PIN` session that reads the certificate from the card saves it.
+ */
+export async function savedCertificate() {
+    const certificate = await Native.savedCertificate();
+    return certificate ? trimDer(certificate) : null;
+}

package/build/native.d.ts

@@ -1,18 +1,46 @@
 /** `saved`: a PIN is saved. `available`: a strong biometric is enrolled, so one can be. `unavailable`: neither. */
 export type PinStatus = 'saved' | 'available' | 'unavailable';
+/** Steps only the native side sees: the card was detected; the PIN is being verified. */
+export type NativeStep = 'detected' | 'pin';
+/** iOS NFC sheet texts: `prompt` while waiting for the card, then one per step. */
+export type NativeMessages = {
+    prompt: string;
+    detected: string;
+    pin: string;
+    ready: string;
+    signing: string;
+};
 type CieSignModule = {
+    /**
+     * Shows the biometric prompt and unlocks the saved PIN for session `id`, which `connect` with a null `pin` then sends to
+     * the card. Returns the certificate saved with the PIN when `useSavedCertificate` and it is of the same card: that
+     * session's `connect` returns it instead of reading it. Null otherwise.
+     */
+    unlock(id: number, biometricPrompt: string, biometricCancel: string, useSavedCertificate: boolean): Promise<Uint8Array | null>;
     /**
      * Waits for the card, verifies the PIN and returns its certificate; NFC session `id` stays open.
-     * A null `pin` unlocks the saved one; `save` saves `pin` once the card accepts it. Each shows the biometric prompt first
-     * only where the secure hardware requires it: unlocking everywhere, saving on Android.
+     * A null `pin` is the one `unlock` unlocked for `id`; `save` saves `pin` once the card accepts it, after the biometric
+     * prompt where the secure hardware requires one (Android).
      */
-    connect(id: number, pin: string | null, save: boolean, prompt: string, biometricPrompt: string, biometricCancel: string): Promise<Uint8Array>;
+    connect(id: number, pin: string | null, save: boolean, messages: NativeMessages, biometricPrompt: string, biometricCancel: string): Promise<Uint8Array>;
     /** Signs a DigestInfo in session `id`, as many times as needed until it closes. */
     sign(id: number, digestInfo: Uint8Array): Promise<Uint8Array>;
-    /** Ends every session up to `id`, also one whose connect has not arrived yet; iOS shows `error` in the NFC sheet. */
-    close(id: number, error: string | null): void;
+    /**
+     * Ends every session up to `id`, also one whose connect has not arrived yet. iOS shows `error` in the NFC sheet, or
+     * else `done` next to its checkmark.
+     */
+    close(id: number, error: string | null, done: string | null): void;
     pinStatus(): Promise<PinStatus>;
     forgetPin(): Promise<void>;
+    /** The certificate file saved with the PIN, without any UI; null when none is saved. */
+    savedCertificate(): Promise<Uint8Array | null>;
+    /** `onStep` fires as session `id` reaches a step only the native side sees. */
+    addListener(event: 'onStep', listener: (event: {
+        id: number;
+        step: NativeStep;
+    }) => void): {
+        remove(): void;
+    };
 };
 declare const _default: CieSignModule;
 export default _default;

package/ios/CieCard.swift

@@ -52,8 +52,12 @@ final class CieCard {
     let ca = try await ok(send(0x00, 0xCB, 0x3F, 0xFF, [0x4D, 0x09, 0x70, 0x07, 0xBF, 0xA0, 0x04, 0x03, 0x7F, 0x49, 0x80]))
     let (caN, caCHR, caCHA) = try (Array(find(0x81, in: ca).drop { $0 == 0 }), find(0x5F20, in: ca), find(0x5F4C, in: ca))
 
+    // Some cards zero-pad q to the length of p (a 256-bit q in 256 bytes): drawn at full length, x would almost never be
+    // below it and this loop would spin until iOS drops the idle session. Draw it over q's significant bytes instead.
+    let order = Array(q.drop { $0 == 0 })
+    guard !order.isEmpty else { throw CieCardError.invalidResponse }
     var x: [UInt8]
-    repeat { x = random(q.count) } while !x.lexicographicallyPrecedes(q)
+    repeat { x = random(order.count) } while !x.lexicographicallyPrecedes(order)
     let pubIFD = try modPow(g, x, p)
     try await ok(send(0x00, 0x22, 0x41, 0xA6, tlv(0x80, [0x9B]) + tlv(0x83, [0x81]) + tlv(0x91, pubIFD)))
     let pubICC = try await find(0x91, in: ok(send(0x00, 0xCB, 0x3F, 0xFF, [0x4D, 0x04, 0xA6, 0x02, 0x91, 0x00])))

package/ios/CieSignModule.swift

@@ -10,15 +10,38 @@ public class CieSignModule: Module {
   public func definition() -> ModuleDefinition {
     Name("CieSign")
 
-    AsyncFunction("connect") {
-      @MainActor (id: Int, pin: String?, save: Bool, prompt: String, biometricPrompt: String, biometricCancel: String) async throws -> Data in
+    Events("onStep")
+
+    AsyncFunction("unlock") {
+      @MainActor (id: Int, biometricPrompt: String, biometricCancel: String, useSavedCertificate: Bool) async throws -> Data? in
       guard NFCTagReaderSession.readingAvailable else { throw failure("NFC_UNAVAILABLE", "NFC tag reading is not available") }
       guard id > self.closed else { throw cancelled }
-      self.reader?.close(nil)
-      let reader = Reader(id: id)
+      self.reader?.close(nil, nil)
+      let reader = Reader(id: id, onStep: self.reporter(id))
       self.reader = reader
       do {
-        return try await reader.connect(pin: pin, save: save, prompt: prompt, biometricPrompt: biometricPrompt, biometricCancel: biometricCancel)
+        return try await reader.unlock(biometricPrompt: biometricPrompt, biometricCancel: biometricCancel, useSavedCertificate: useSavedCertificate)
+      } catch {
+        throw coded(error)
+      }
+    }
+
+    // `messages`: NFC sheet texts by step, `prompt` first. A nil `pin` continues the session `unlock` started.
+    AsyncFunction("connect") {
+      @MainActor (id: Int, pin: String?, save: Bool, messages: [String: String], biometricPrompt: String, biometricCancel: String) async throws -> Data in
+      guard NFCTagReaderSession.readingAvailable else { throw failure("NFC_UNAVAILABLE", "NFC tag reading is not available") }
+      guard id > self.closed else { throw cancelled }
+      let reader: Reader
+      if pin == nil {
+        guard let unlocked = self.reader, unlocked.id == id else { throw cancelled }
+        reader = unlocked
+      } else {
+        self.reader?.close(nil, nil)
+        reader = Reader(id: id, onStep: self.reporter(id))
+        self.reader = reader
+      }
+      do {
+        return try await reader.connect(pin: pin, save: save, messages: messages)
       } catch {
         let error = coded(reader.invalidation ?? error)
         if pin == nil, let code = (error as? Exception)?.code, code.hasPrefix("WRONG_PIN") || code == "PIN_LOCKED" { SavedPin.delete() }
@@ -30,16 +53,17 @@ public class CieSignModule: Module {
       guard let reader = self.reader, reader.id == id else { throw cancelled }
       do {
         guard let card = reader.card else { throw cancelled }  // the reason is in `invalidation`, e.g. a timeout
+        reader.show("signing")
         return try await card.sign(digestInfo)
       } catch {
         throw coded(reader.invalidation ?? error)
       }
     }
 
-    AsyncFunction("close") { @MainActor (id: Int, error: String?) async in
+    AsyncFunction("close") { @MainActor (id: Int, error: String?, done: String?) async in
       self.closed = max(self.closed, id)
       guard let reader = self.reader, reader.id <= id else { return }
-      reader.close(error)
+      reader.close(error, done)
       self.reader = nil
     }
 
@@ -49,42 +73,74 @@ public class CieSignModule: Module {
 
     AsyncFunction("forgetPin") { SavedPin.delete() }
 
+    AsyncFunction("savedCertificate") { () -> Data? in SavedPin.certificate()?.certificate }
+
     OnDestroy {
-      DispatchQueue.main.async { self.reader?.close(nil) }
+      DispatchQueue.main.async { self.reader?.close(nil, nil) }
     }
   }
+
+  /// Sends session `id`'s steps to JS as `onStep` events, without keeping the module alive.
+  private func reporter(_ id: Int) -> (String) -> Void {
+    { [weak self] step in self?.sendEvent("onStep", ["id": id, "step": step]) }
+  }
 }
 
 /// One NFCTagReaderSession; used on the main thread only.
 private final class Reader: NSObject, NFCTagReaderSessionDelegate {
   let id: Int
+  private var messages: [String: String] = [:]
+  private let onStep: (String) -> Void
   private var session: NFCTagReaderSession?
   private var pending: CheckedContinuation<Data, Error>?
   private var pin = ""
   private var save = false
   private var owner: Data?  // NIS of the card the saved PIN belongs to
+  private var savedCertificate: Data?  // that card's certificate file, when the session uses it instead of reading it
   private var biometrics: LAContext?
   private var closed = false
   private(set) var card: CieCard?
   private(set) var invalidation: Error?
 
-  init(id: Int) {
+  init(id: Int, onStep: @escaping (String) -> Void) {
     self.id = id
+    self.onStep = onStep
+  }
+
+  /// Shows the NFC sheet text for `step`, if any.
+  func show(_ step: String) {
+    if let message = messages[step] { session?.alertMessage = message }
+  }
+
+  /// Shows `step` in the NFC sheet and reports it to JS.
+  private func reach(_ step: String) {
+    show(step)
+    onStep(step)
+  }
+
+  /// Unlocks the saved PIN with Face ID or Touch ID for `connect`. With `useSavedCertificate`, returns the certificate saved
+  /// with it, when it is of the same card: `connect` then returns it instead of reading it from the card.
+  func unlock(biometricPrompt: String, biometricCancel: String, useSavedCertificate: Bool) async throws -> Data? {
+    let context = LAContext()
+    context.localizedCancelTitle = biometricCancel
+    context.localizedFallbackTitle = ""
+    biometrics = context
+    (pin, owner) = try await SavedPin.unlock(context, reason: biometricPrompt)
+    guard !closed else { throw cancelled }
+    if useSavedCertificate, let saved = SavedPin.certificate(), saved.card == owner { savedCertificate = saved.certificate }
+    return savedCertificate
   }
 
-  /// A nil `pin` unlocks the saved one with Face ID or Touch ID; `save` saves `pin` once the card accepts it, with no
-  /// prompt, since writing the Keychain item needs no authentication.
-  func connect(pin: String?, save: Bool, prompt: String, biometricPrompt: String, biometricCancel: String) async throws -> Data {
+  /// A nil `pin` is the saved one `unlock` unlocked; `save` saves `pin` once the card accepts it, with no prompt, since
+  /// writing the Keychain item needs no authentication.
+  func connect(pin: String?, save: Bool, messages: [String: String]) async throws -> Data {
     if let pin {
       if save, !SavedPin.canSave { throw SavedPinError.biometryUnavailable }
       (self.pin, self.save) = (pin, save)
-    } else {
-      let context = LAContext()
-      context.localizedCancelTitle = biometricCancel
-      context.localizedFallbackTitle = ""
-      biometrics = context
-      (self.pin, owner) = try await SavedPin.unlock(context, reason: biometricPrompt)
+    } else if owner == nil {
+      throw SavedPinError.notSaved
     }
+    self.messages = messages
     guard !closed else { throw cancelled }
     return try await withCheckedThrowingContinuation { continuation in
       guard let session = NFCTagReaderSession(pollingOption: .iso14443, delegate: self, queue: .main) else {
@@ -92,16 +148,22 @@ private final class Reader: NSObject, NFCTagReaderSessionDelegate {
       }
       pending = continuation
       self.session = session
-      session.alertMessage = prompt
+      show("prompt")
       session.begin()
     }
   }
 
-  func close(_ error: String?) {
+  /// Ends the session; the NFC sheet shows `error` if there is one, otherwise `done` next to its checkmark.
+  func close(_ error: String?, _ done: String?) {
     closed = true
     biometrics?.invalidate()
     finish(.failure(cancelled))
-    if let error { session?.invalidate(errorMessage: error) } else { session?.invalidate() }
+    if let error {
+      session?.invalidate(errorMessage: error)
+    } else {
+      if let done { session?.alertMessage = done }
+      session?.invalidate()
+    }
     session = nil
     card = nil
   }
@@ -120,6 +182,7 @@ private final class Reader: NSObject, NFCTagReaderSessionDelegate {
     Task { @MainActor in
       do {
         try await session.connect(to: tags[0])
+        reach("detected")
         let card = CieCard { apdu in
           guard let command = NFCISO7816APDU(data: apdu) else { throw failure("CARD_ERROR", "Malformed APDU") }
           let (data, sw1, sw2) = try await tag.sendCommand(apdu: command)
@@ -127,10 +190,18 @@ private final class Reader: NSObject, NFCTagReaderSessionDelegate {
         }
         let serviceId = try await card.serviceId()
         if let owner, owner != serviceId { throw SavedPinError.otherCard }
+        reach("pin")
         try await card.open(pin: pin)
         if save { try SavedPin.store(pin, card: serviceId) }
-        let certificate = try await card.certificate()
+        let certificate: Data
+        if let savedCertificate {
+          certificate = savedCertificate
+        } else {
+          certificate = try await card.certificate()
+          if save || owner != nil { SavedPin.storeCertificate(certificate, card: serviceId) }
+        }
         self.card = card
+        show("ready")  // JS reports `ready` once connect resolves
         finish(.success(certificate))
       } catch let error as NFCReaderError where error.code == .readerTransceiveErrorSessionInvalidated {
         // didInvalidateWithError follows with the reason (cancel, timeout).

package/ios/SavedPin.swift

@@ -7,9 +7,11 @@ enum SavedPinError: Error {
 }
 
 /// The CIE PIN as a Keychain item that the Secure Enclave releases only after Face ID or Touch ID matches one of the
-/// faces or fingers enrolled when it was saved. It is never synced, backed up or restored to another device.
+/// faces or fingers enrolled when it was saved. It is never synced, backed up or restored to another device. Next to it,
+/// its card's certificate: public, so readable without biometrics, and replaced or deleted with the PIN.
 enum SavedPin {
   private static let item: [CFString: Any] = [kSecClass: kSecClassGenericPassword, kSecAttrService: "it.codingduck.ciesign.pin"]
+  private static let certificateItem: [CFString: Any] = [kSecClass: kSecClassGenericPassword, kSecAttrService: "it.codingduck.ciesign.certificate"]
 
   static var canSave: Bool { LAContext().canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil) }
 
@@ -63,8 +65,28 @@ enum SavedPin {
     return (String(decoding: pin, as: UTF8.self), card)
   }
 
+  /// Saves the certificate file of the card whose PIN is saved; `card` is its NIS. Best effort: without it, sessions read
+  /// the certificate from the card.
+  static func storeCertificate(_ certificate: Data, card: Data) {
+    SecItemDelete(certificateItem as CFDictionary)
+    let attributes: [CFString: Any] = [kSecAttrAccessible: kSecAttrAccessibleWhenUnlockedThisDeviceOnly, kSecAttrGeneric: card, kSecValueData: certificate]
+    SecItemAdd(certificateItem.merging(attributes) { $1 } as CFDictionary, nil)
+  }
+
+  /// The certificate file saved with the PIN and its card's NIS, without any UI; nil when none is saved.
+  static func certificate() -> (certificate: Data, card: Data)? {
+    guard isSaved else { return nil }
+    var result: CFTypeRef?
+    let query = certificateItem.merging([kSecReturnData: true, kSecReturnAttributes: true]) { $1 }
+    guard SecItemCopyMatching(query as CFDictionary, &result) == errSecSuccess, let found = result as? [CFString: Any],
+          let certificate = found[kSecValueData] as? Data, let card = found[kSecAttrGeneric] as? Data
+    else { return nil }
+    return (certificate, card)
+  }
+
   static func delete() {
     SecItemDelete(item as CFDictionary)
+    SecItemDelete(certificateItem as CFDictionary)
   }
 
   private static func access() -> SecAccessControl? {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciesign-react-native",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "RSA signatures with the Italian electronic identity card (CIE) over NFC",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/src/index.ts

@@ -10,11 +10,44 @@ export const SAVED_PIN: unique symbol = Symbol('SAVED_PIN');
 export type Pin = string | typeof SAVED_PIN;
 
 /**
- * `prompt`, `error`: texts of the iOS NFC sheet. `savePin`: once the card accepts the PIN, save it for `SAVED_PIN`.
- * `biometricPrompt`, `biometricCancel`: texts of the biometric prompt shown before the card is read, wherever the secure
- * hardware requires one: `SAVED_PIN` everywhere, `savePin` on Android only.
+ * Progress of a session, in order: `detected` the card is on the phone; `pin` the PIN is being verified; `ready` the PIN
+ * is verified and the certificate read (or taken from the saved one), `use` starts; `signing` a signature starts, once
+ * per `sign`; `done` `use` resolved and the session is over.
  */
-export type CieOptions = { prompt?: string; error?: string; savePin?: boolean; biometricPrompt?: string; biometricCancel?: string };
+export type CieStep = 'detected' | 'pin' | 'ready' | 'signing' | 'done';
+
+const STEPS: CieStep[] = ['detected', 'pin', 'ready', 'signing', 'done'];
+
+const MESSAGES: Record<CieStep, string> = {
+  detected: 'CIE rilevata, non allontanarla',
+  pin: 'Verifica del PIN…',
+  ready: 'PIN verificato',
+  signing: 'Firma in corso…',
+  done: 'Operazione completata',
+};
+
+/**
+ * `prompt`, `error`: texts of the iOS NFC sheet while it waits for the card and when the session fails; `messages`: its
+ * text at each step. `onStep`: called at each step, e.g. to show progress on Android, which has no NFC sheet.
+ * `savePin`: once the card accepts the PIN, save it for `SAVED_PIN`, with the card certificate. `biometricPrompt`,
+ * `biometricCancel`: texts of the biometric prompt shown before the card is read, wherever the secure hardware requires
+ * one: `SAVED_PIN` everywhere, `savePin` on Android only. `useSavedCertificate`: with `SAVED_PIN`, skip reading the
+ * certificate from the card and use the one saved with the PIN (see `savedCertificate`), when there is one.
+ * `beforeCard`: with `SAVED_PIN`, runs once the biometric prompt has unlocked the PIN and before the NFC session waits for
+ * the card, with the saved certificate the session will use (`useSavedCertificate`), or null: the session waits for it, so
+ * what to sign can be prepared after the prompt and outside iOS's 60-second NFC limit.
+ */
+export type CieOptions = {
+  prompt?: string;
+  error?: string;
+  messages?: Partial<Record<CieStep, string>>;
+  onStep?: (step: CieStep) => void;
+  savePin?: boolean;
+  biometricPrompt?: string;
+  biometricCancel?: string;
+  useSavedCertificate?: boolean;
+  beforeCard?: (savedCertificate: Bytes | null) => Promise<void>;
+};
 
 /** A card whose PIN has been verified, for as long as `use` runs. */
 export type CieSession = {
@@ -38,15 +71,35 @@ export async function cieSession<T>(pin: Pin, use: (session: CieSession) => Prom
     savePin = false,
     biometricPrompt = pin === SAVED_PIN ? 'Sblocca il PIN della CIE' : 'Salva il PIN della CIE',
     biometricCancel = 'Annulla',
+    useSavedCertificate = false,
+    onStep,
+    beforeCard,
   } = options;
+  const message = (s: CieStep) => options.messages?.[s] ?? MESSAGES[s];
   const id = ++session;
   let done = false;
+  // Native events can arrive after `ready`: steps only move forward, except one `signing` per signature.
+  let reached = -1;
+  const step = (s: CieStep) => {
+    const i = STEPS.indexOf(s);
+    if (i < reached || (i === reached && s !== 'signing')) return;
+    reached = i;
+    onStep?.(s);
+  };
+  const subscription = onStep && Native.addListener('onStep', (event) => event.id === id && step(event.step));
   try {
-    const certificate = trimDer(await Native.connect(id, pin === SAVED_PIN ? null : pin, savePin, prompt, biometricPrompt, biometricCancel));
+    const sheet = { prompt, detected: message('detected'), pin: message('pin'), ready: message('ready'), signing: message('signing') };
+    if (pin === SAVED_PIN) {
+      const saved = await Native.unlock(id, biometricPrompt, biometricCancel, useSavedCertificate);
+      await beforeCard?.(saved && trimDer(saved));
+    }
+    const certificate = trimDer(await Native.connect(id, pin === SAVED_PIN ? null : pin, savePin, sheet, biometricPrompt, biometricCancel));
+    step('ready');
     let last: Promise<unknown> = Promise.resolve();
     const sign = (digestInfo: Bytes) => {
       const input = digestInfo.slice(); // signed later, once the calls before it finish
       const signature = last.then(async () => {
+        step('signing');
         const signature = await Native.sign(id, input);
         verify(certificate, input, signature);
         return signature;
@@ -58,15 +111,27 @@ export async function cieSession<T>(pin: Pin, use: (session: CieSession) => Prom
     done = true;
     return result;
   } finally {
-    Native.close(id, done ? null : error);
+    subscription?.remove();
+    Native.close(id, done ? null : error, done ? message('done') : null);
+    if (done) step('done');
   }
 }
 
 /** Aborts the CIE session in progress. */
-export const cancel = () => Native.close(session, null);
+export const cancel = () => Native.close(session, null, null);
 
 /** Whether a PIN is saved, without showing any UI. */
 export const pinStatus = (): Promise<PinStatus> => Native.pinStatus();
 
-/** Deletes the saved PIN. */
+/** Deletes the saved PIN and its certificate. */
 export const forgetPin = (): Promise<void> => Native.forgetPin();
+
+/**
+ * The DER certificate of the card whose PIN is saved, without any UI: known before the card is on the phone, e.g. to
+ * prepare what to sign before a `SAVED_PIN` session with `useSavedCertificate`. Null when no PIN is saved, or none was
+ * saved with it yet: a `SAVED_PIN` session that reads the certificate from the card saves it.
+ */
+export async function savedCertificate(): Promise<Bytes | null> {
+  const certificate = await Native.savedCertificate();
+  return certificate ? trimDer(certificate) : null;
+}

package/src/native.ts

@@ -3,19 +3,38 @@ import { requireNativeModule } from 'expo';
 /** `saved`: a PIN is saved. `available`: a strong biometric is enrolled, so one can be. `unavailable`: neither. */
 export type PinStatus = 'saved' | 'available' | 'unavailable';
 
+/** Steps only the native side sees: the card was detected; the PIN is being verified. */
+export type NativeStep = 'detected' | 'pin';
+
+/** iOS NFC sheet texts: `prompt` while waiting for the card, then one per step. */
+export type NativeMessages = { prompt: string; detected: string; pin: string; ready: string; signing: string };
+
 type CieSignModule = {
+  /**
+   * Shows the biometric prompt and unlocks the saved PIN for session `id`, which `connect` with a null `pin` then sends to
+   * the card. Returns the certificate saved with the PIN when `useSavedCertificate` and it is of the same card: that
+   * session's `connect` returns it instead of reading it. Null otherwise.
+   */
+  unlock(id: number, biometricPrompt: string, biometricCancel: string, useSavedCertificate: boolean): Promise<Uint8Array | null>;
   /**
    * Waits for the card, verifies the PIN and returns its certificate; NFC session `id` stays open.
-   * A null `pin` unlocks the saved one; `save` saves `pin` once the card accepts it. Each shows the biometric prompt first
-   * only where the secure hardware requires it: unlocking everywhere, saving on Android.
+   * A null `pin` is the one `unlock` unlocked for `id`; `save` saves `pin` once the card accepts it, after the biometric
+   * prompt where the secure hardware requires one (Android).
    */
-  connect(id: number, pin: string | null, save: boolean, prompt: string, biometricPrompt: string, biometricCancel: string): Promise<Uint8Array>;
+  connect(id: number, pin: string | null, save: boolean, messages: NativeMessages, biometricPrompt: string, biometricCancel: string): Promise<Uint8Array>;
   /** Signs a DigestInfo in session `id`, as many times as needed until it closes. */
   sign(id: number, digestInfo: Uint8Array): Promise<Uint8Array>;
-  /** Ends every session up to `id`, also one whose connect has not arrived yet; iOS shows `error` in the NFC sheet. */
-  close(id: number, error: string | null): void;
+  /**
+   * Ends every session up to `id`, also one whose connect has not arrived yet. iOS shows `error` in the NFC sheet, or
+   * else `done` next to its checkmark.
+   */
+  close(id: number, error: string | null, done: string | null): void;
   pinStatus(): Promise<PinStatus>;
   forgetPin(): Promise<void>;
+  /** The certificate file saved with the PIN, without any UI; null when none is saved. */
+  savedCertificate(): Promise<Uint8Array | null>;
+  /** `onStep` fires as session `id` reaches a step only the native side sees. */
+  addListener(event: 'onStep', listener: (event: { id: number; step: NativeStep }) => void): { remove(): void };
 };
 
 export default requireNativeModule<CieSignModule>('CieSign');