ciesign-react-native 0.1.0 → 0.2.0

package/README.md

@@ -66,7 +66,7 @@ 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? })` | 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). |
@@ -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: `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.

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

@@ -33,8 +33,11 @@ class CieSignModule : Module() {
   override fun definition() = ModuleDefinition {
     Name("CieSign")
 
+    Events("onStep")
+
     // 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 ->
+    // 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)
@@ -77,7 +80,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()
@@ -144,6 +147,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,6 +159,7 @@ 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)
+      step(id, "pin")
       val certificate = c.open(pin)
       if (sealed != null) savedPin.store(nis, sealed)
       synchronized(lock) {
@@ -169,6 +174,8 @@ 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

package/build/index.d.ts

@@ -6,13 +6,23 @@ 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, `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`. `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.
  */
 export type CieOptions = {
     prompt?: string;
     error?: string;
+    messages?: Partial<Record<CieStep, string>>;
+    onStep?: (step: CieStep) => void;
     savePin?: boolean;
     biometricPrompt?: string;
     biometricCancel?: string;

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,29 @@ 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', onStep, } = 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') };
+        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,11 +53,14 @@ 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. */

package/build/native.d.ts

@@ -1,18 +1,38 @@
 /** `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 = {
     /**
      * 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.
      */
-    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>;
+    /** `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/CieSignModule.swift

@@ -10,15 +10,18 @@ public class CieSignModule: Module {
   public func definition() -> ModuleDefinition {
     Name("CieSign")
 
+    Events("onStep")
+
+    // `messages`: NFC sheet texts by step, `prompt` first.
     AsyncFunction("connect") {
-      @MainActor (id: Int, pin: String?, save: Bool, prompt: String, biometricPrompt: String, biometricCancel: String) async throws -> Data in
+      @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 }
-      self.reader?.close(nil)
-      let reader = Reader(id: id)
+      self.reader?.close(nil, nil)
+      let reader = Reader(id: id, messages: messages, 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.connect(pin: pin, save: save, biometricPrompt: biometricPrompt, biometricCancel: biometricCancel)
       } 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 +33,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
     }
 
@@ -50,14 +54,21 @@ public class CieSignModule: Module {
     AsyncFunction("forgetPin") { SavedPin.delete() }
 
     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 let messages: [String: String]
+  private let onStep: (String) -> Void
   private var session: NFCTagReaderSession?
   private var pending: CheckedContinuation<Data, Error>?
   private var pin = ""
@@ -68,13 +79,26 @@ private final class Reader: NSObject, NFCTagReaderSessionDelegate {
   private(set) var card: CieCard?
   private(set) var invalidation: Error?
 
-  init(id: Int) {
+  init(id: Int, messages: [String: String], onStep: @escaping (String) -> Void) {
     self.id = id
+    self.messages = messages
+    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)
   }
 
   /// 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 {
+  func connect(pin: String?, save: Bool, biometricPrompt: String, biometricCancel: String) async throws -> Data {
     if let pin {
       if save, !SavedPin.canSave { throw SavedPinError.biometryUnavailable }
       (self.pin, self.save) = (pin, save)
@@ -92,16 +116,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 +150,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 +158,12 @@ 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()
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciesign-react-native",
-  "version": "0.1.0",
+  "version": "0.2.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,38 @@ 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, `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`. `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.
+ */
+export type CieOptions = {
+  prompt?: string;
+  error?: string;
+  messages?: Partial<Record<CieStep, string>>;
+  onStep?: (step: CieStep) => void;
+  savePin?: boolean;
+  biometricPrompt?: string;
+  biometricCancel?: string;
+};
 
 /** A card whose PIN has been verified, for as long as `use` runs. */
 export type CieSession = {
@@ -38,15 +65,29 @@ 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',
+    onStep,
   } = 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') };
+    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,12 +99,14 @@ 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();

package/src/native.ts

@@ -3,19 +3,30 @@ 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 = {
   /**
    * 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.
    */
-  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>;
+  /** `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');