ciesign-react-native 0.0.1 → 0.2.0

package/ios/CieSignModule.swift

@@ -0,0 +1,209 @@
+import CoreNFC
+import ExpoModulesCore
+import LocalAuthentication
+
+public class CieSignModule: Module {
+  // Main-actor state. Ids come from JS; sessions up to `closed` are over, even if their connect arrives later.
+  private var reader: Reader?
+  private var closed = 0
+
+  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, 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, 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, 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() }
+        throw error
+      }
+    }
+
+    AsyncFunction("sign") { @MainActor (id: Int, digestInfo: Data) async throws -> Data in
+      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?, done: String?) async in
+      self.closed = max(self.closed, id)
+      guard let reader = self.reader, reader.id <= id else { return }
+      reader.close(error, done)
+      self.reader = nil
+    }
+
+    AsyncFunction("pinStatus") { () -> String in
+      SavedPin.isSaved ? "saved" : SavedPin.canSave ? "available" : "unavailable"
+    }
+
+    AsyncFunction("forgetPin") { SavedPin.delete() }
+
+    OnDestroy {
+      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 = ""
+  private var save = false
+  private var owner: Data?  // NIS of the card the saved PIN belongs to
+  private var biometrics: LAContext?
+  private var closed = false
+  private(set) var card: CieCard?
+  private(set) var invalidation: Error?
+
+  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, biometricPrompt: String, biometricCancel: 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)
+    }
+    guard !closed else { throw cancelled }
+    return try await withCheckedThrowingContinuation { continuation in
+      guard let session = NFCTagReaderSession(pollingOption: .iso14443, delegate: self, queue: .main) else {
+        return continuation.resume(throwing: failure("NFC_UNAVAILABLE", "NFC tag reading is not available"))
+      }
+      pending = continuation
+      self.session = session
+      show("prompt")
+      session.begin()
+    }
+  }
+
+  /// 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 {
+      if let done { session?.alertMessage = done }
+      session?.invalidate()
+    }
+    session = nil
+    card = nil
+  }
+
+  func tagReaderSessionDidBecomeActive(_ session: NFCTagReaderSession) {}
+
+  func tagReaderSession(_ session: NFCTagReaderSession, didInvalidateWithError error: Error) {
+    invalidation = error
+    card = nil
+    finish(.failure(error))
+  }
+
+  func tagReaderSession(_ session: NFCTagReaderSession, didDetect tags: [NFCTag]) {
+    guard tags.count == 1 else { return session.restartPolling() }
+    guard case let .iso7816(tag) = tags[0] else { return finish(.failure(failure("NOT_A_CIE", "Not an ISO 7816 card"))) }
+    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)
+          return data + [sw1, sw2]
+        }
+        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).
+      } catch {
+        finish(.failure(error))
+      }
+    }
+  }
+
+  private func finish(_ result: Result<Data, Error>) {
+    pending?.resume(with: result)
+    pending = nil
+  }
+}
+
+private func failure(_ code: String, _ description: String) -> Exception {
+  Exception(name: code, description: description, code: code)
+}
+
+private var cancelled: Exception { failure("CANCELLED", "Cancelled") }
+
+private func coded(_ error: Error) -> Error {
+  switch error {
+  case let error as Exception: return error
+  case CieCardError.wrongPin(let attemptsLeft): return failure("WRONG_PIN_\(attemptsLeft)", "Wrong PIN")
+  case CieCardError.pinLocked: return failure("PIN_LOCKED", "PIN locked: unlock it with the PUK")
+  case CieCardError.notCie: return failure("NOT_A_CIE", "Not a CIE")
+  case SavedPinError.notSaved: return failure("PIN_NOT_SAVED", "No saved PIN")
+  case SavedPinError.otherCard: return failure("WRONG_CARD", "Not the card the PIN was saved for")
+  case SavedPinError.biometryUnavailable: return failure("BIOMETRIC_UNAVAILABLE", "Face ID or Touch ID is not available")
+  case SavedPinError.cancelled: return cancelled
+  case let error as NFCReaderError:
+    switch error.code {
+    case .readerSessionInvalidationErrorUserCanceled, .readerTransceiveErrorSessionInvalidated: return cancelled
+    case .readerSessionInvalidationErrorSessionTimeout: return failure("TIMEOUT", "NFC session timed out")
+    case .readerSessionInvalidationErrorSystemIsBusy: return failure("BUSY", "NFC is busy, retry")
+    case .readerTransceiveErrorTagConnectionLost, .readerTransceiveErrorTagResponseError, .readerTransceiveErrorTagNotConnected:
+      return failure("TAG_LOST", "Card connection lost")
+    default: return failure("CARD_ERROR", error.localizedDescription)
+    }
+  default: return failure("CARD_ERROR", "\(error)")
+  }
+}

package/ios/SavedPin.swift

@@ -0,0 +1,73 @@
+import Foundation
+import LocalAuthentication
+import Security
+
+enum SavedPinError: Error {
+  case notSaved, otherCard, biometryUnavailable, cancelled
+}
+
+/// 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.
+enum SavedPin {
+  private static let item: [CFString: Any] = [kSecClass: kSecClassGenericPassword, kSecAttrService: "it.codingduck.ciesign.pin"]
+
+  static var canSave: Bool { LAContext().canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil) }
+
+  /// Checks for the item without showing any UI.
+  static var isSaved: Bool {
+    let context = LAContext()
+    context.interactionNotAllowed = true
+    let status = SecItemCopyMatching(item.merging([kSecUseAuthenticationContext: context]) { $1 } as CFDictionary, nil)
+    return status == errSecSuccess || status == errSecInteractionNotAllowed
+  }
+
+  /// Replaces the saved PIN; `card` is the NIS of the card that accepted it.
+  static func store(_ pin: String, card: Data) throws {
+    delete()
+    guard let access = access(),
+          SecItemAdd(item.merging([kSecAttrAccessControl: access, kSecAttrGeneric: card, kSecValueData: Data(pin.utf8)]) { $1 } as CFDictionary, nil)
+            == errSecSuccess
+    else { throw SavedPinError.biometryUnavailable }
+  }
+
+  /// Evaluates the item's access control, which the Keychain read then requires; invalidating `context` cancels it.
+  private static func authenticate(_ context: LAContext, reason: String) async throws {
+    do {
+      guard let access = access(), try await context.evaluateAccessControl(access, operation: .useItem, localizedReason: reason) else {
+        throw SavedPinError.biometryUnavailable
+      }
+    } catch let error as LAError {
+      switch error.code {
+      case .userCancel, .appCancel, .systemCancel, .userFallback: throw SavedPinError.cancelled
+      case .biometryNotEnrolled:  // removing every face or finger invalidated the item
+        delete()
+        throw SavedPinError.notSaved
+      default: throw SavedPinError.biometryUnavailable
+      }
+    }
+  }
+
+  /// Authenticates with `context` and returns the PIN with its card's NIS.
+  static func unlock(_ context: LAContext, reason: String) async throws -> (pin: String, card: Data) {
+    guard isSaved else { throw SavedPinError.notSaved }
+    try await authenticate(context, reason: reason)
+    context.interactionNotAllowed = true
+    var result: CFTypeRef?
+    let query = item.merging([kSecUseAuthenticationContext: context, kSecReturnData: true, kSecReturnAttributes: true]) { $1 }
+    guard SecItemCopyMatching(query as CFDictionary, &result) == errSecSuccess, let found = result as? [CFString: Any],
+          let pin = found[kSecValueData] as? Data, let card = found[kSecAttrGeneric] as? Data
+    else {
+      delete()  // the enrolled faces or fingers changed since the PIN was saved
+      throw SavedPinError.notSaved
+    }
+    return (String(decoding: pin, as: UTF8.self), card)
+  }
+
+  static func delete() {
+    SecItemDelete(item as CFDictionary)
+  }
+
+  private static func access() -> SecAccessControl? {
+    SecAccessControlCreateWithFlags(nil, kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly, .biometryCurrentSet, nil)
+  }
+}

package/package.json

@@ -1 +1,47 @@
-{"name":"ciesign-react-native","version":"0.0.1","description":"Name reservation, use >=0.1.0"}
+{
+  "name": "ciesign-react-native",
+  "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",
+  "files": [
+    "build",
+    "src",
+    "android/build.gradle",
+    "android/src",
+    "ios",
+    "app.plugin.js",
+    "expo-module.config.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "node --import ./test/hooks.mjs --test test/*.test.ts"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "cie",
+    "nfc",
+    "electronic-signature",
+    "firma-elettronica",
+    "carta-identita-elettronica"
+  ],
+  "author": "Coding Duck S.r.l.",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "expo": "~58.0.23",
+    "typescript": "~6.0.3"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "react-native": "*"
+  },
+  "homepage": "https://github.com/codingducksrl/ciesign-react-native#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codingducksrl/ciesign-react-native.git"
+  },
+  "bugs": "https://github.com/codingducksrl/ciesign-react-native/issues"
+}

package/src/certificate.ts

@@ -0,0 +1,47 @@
+export type Bytes = Uint8Array;
+
+export const fail = (code: string, message: string) => Object.assign(new Error(message), { code });
+
+const hex = (bytes: Bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+
+/** Value start and end offsets of the DER TLV at `i`. */
+const bounds = (der: Bytes, i = 0) => {
+  let length = der[i + 1];
+  let start = i + 2;
+  if (length & 0x80) {
+    const n = length & 0x7f;
+    length = 0;
+    for (let k = 0; k < n; k++) length = length * 256 + der[start++];
+  }
+  return { start, end: start + length };
+};
+
+/** The TLVs inside a constructed DER value. */
+const children = (der: Bytes): Bytes[] => {
+  const out: Bytes[] = [];
+  for (let i = bounds(der).start; i < bounds(der).end; i = bounds(der, i).end) out.push(der.subarray(i, bounds(der, i).end));
+  return out;
+};
+
+const value = (der: Bytes) => der.subarray(bounds(der).start, bounds(der).end);
+
+/** Drops the padding after the certificate (the CIE stores it in a zero-filled file). */
+export const trimDer = (der: Bytes) => {
+  const { end } = bounds(der);
+  if (der[0] !== 0x30 || !(end <= der.length)) throw fail('CARD_ERROR', 'Invalid certificate');
+  return der.subarray(0, end);
+};
+
+/** Checks an RSA PKCS#1 v1.5 signature of `digestInfo` against the certificate's public key. */
+export const verify = (certificate: Bytes, digestInfo: Bytes, signature: Bytes) => {
+  const fields = children(children(certificate)[0]); // TBSCertificate, with or without [0] version
+  const spki = children(fields[fields[0][0] === 0xa0 ? 6 : 5]);
+  const [n, e] = children(value(spki[1]).subarray(1)).map((i) => BigInt('0x' + hex(value(i))));
+  let result = 1n;
+  for (let base = BigInt('0x' + (hex(signature) || '0')) % n, x = e; x > 0n; x >>= 1n, base = (base * base) % n) {
+    if (x & 1n) result = (result * base) % n;
+  }
+  const k = (n.toString(16).length + 1) >> 1;
+  const encoded = '01' + 'ff'.repeat(k - digestInfo.length - 3) + '00' + hex(digestInfo);
+  if (signature.length !== k || result !== BigInt('0x' + encoded)) throw fail('CARD_ERROR', 'The signature does not match the certificate');
+};

package/src/index.ts

@@ -0,0 +1,115 @@
+import { type Bytes, trimDer, verify } from './certificate';
+import Native, { type PinStatus } from './native';
+
+export type { PinStatus } 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: unique symbol = Symbol('SAVED_PIN');
+
+/** The full 8-digit PIN, or `SAVED_PIN`. */
+export type Pin = string | typeof SAVED_PIN;
+
+/**
+ * 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';
+
+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 = {
+  /** DER authentication certificate; its subject holds the holder's name and fiscal code. */
+  certificate: Bytes;
+  /** RSA PKCS#1 v1.5 signature of a DER DigestInfo, checked against `certificate`. Calls run one at a time. */
+  sign(digestInfo: Bytes): Promise<Bytes>;
+};
+
+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
+ * `use` settles.
+ */
+export async function cieSession<T>(pin: Pin, use: (session: CieSession) => Promise<T>, options: CieOptions = {}): Promise<T> {
+  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',
+    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 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;
+      });
+      last = signature.catch(() => {});
+      return signature;
+    };
+    const result = await use({ certificate, sign });
+    done = true;
+    return result;
+  } finally {
+    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, null);
+
+/** Whether a PIN is saved, without showing any UI. */
+export const pinStatus = (): Promise<PinStatus> => Native.pinStatus();
+
+/** Deletes the saved PIN. */
+export const forgetPin = (): Promise<void> => Native.forgetPin();

package/src/native.ts

@@ -0,0 +1,32 @@
+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, 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, 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');