ciesign-react-native 0.0.0-stage → 0.1.0

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,6 +1,47 @@
 {
   "name": "ciesign-react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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,72 @@
+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;
+
+/**
+ * `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.
+ */
+export type CieOptions = { prompt?: string; error?: string; 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',
+  } = options;
+  const id = ++session;
+  let done = false;
+  try {
+    const certificate = trimDer(await Native.connect(id, pin === SAVED_PIN ? null : pin, savePin, prompt, biometricPrompt, biometricCancel));
+    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 () => {
+        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 {
+    Native.close(id, done ? null : error);
+  }
+}
+
+/** Aborts the CIE session in progress. */
+export const cancel = () => Native.close(session, 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,21 @@
+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';
+
+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>;
+  /** 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;
+  pinStatus(): Promise<PinStatus>;
+  forgetPin(): Promise<void>;
+};
+
+export default requireNativeModule<CieSignModule>('CieSign');