@pagopa/io-react-native-iso18013 0.1.0

package/src/cbor/cbor/decoder.ts

@@ -0,0 +1,56 @@
+import { IoReactNativeCbor } from '..';
+import {
+  Documents,
+  DocumentsFromString,
+  IssuerSigned,
+  IssuerSignedFromString,
+} from './schema';
+import { coerceToJSON } from './schema.utils';
+
+/**
+ * Decode base64 encoded CBOR data to JSON object.
+ *
+ * If it is not possibile to decode the provided data, the promise will be rejected with
+ * an instance of {@link CborFailure}.
+ *
+ * **NOTE**: this method does not handle nested CBOR data, which will need additional
+ * parsing.
+ *
+ * @param data - The base64 or base64url encoded CBOR data
+ * @returns The decoded data as JSON object
+ */
+export const decode = async (data: string): Promise<any> => {
+  const jsonString = await IoReactNativeCbor.decode(data);
+  return await coerceToJSON.parseAsync(jsonString);
+};
+
+/**
+ * Decode base64 or base64url encoded CBOR data to mDOC object
+ *
+ * If it is not possibile to decode the provided data, the promise will be rejected with
+ * an instance of {@link CborFailure}.
+ *
+ * @param data - The base64 encoded MDOC data
+ * @returns The decoded data as mDOC object
+ */
+export const decodeDocuments = async (data: string): Promise<Documents> => {
+  const documentsString = await IoReactNativeCbor.decodeDocuments(data);
+  return await DocumentsFromString.parseAsync(documentsString);
+};
+
+/**
+ * Extract and decode the {@link IssuerSigned} with the {@link IssuerAuth} decoded from base64 encoded CBOR
+ *
+ * If it is not possibile to decode the provided data, the promise will be rejected with
+ * an instance of {@link CborFailure}.
+ *
+ * @param issuerSigned - The base64 or base64url encoded MDOC data
+ * @returns The decoded {@link IssuerSigned} contained in the mDOC object
+ */
+export const decodeIssuerSigned = async (
+  issuerSigned: string
+): Promise<IssuerSigned> => {
+  const decodedIssuerSignedString =
+    await IoReactNativeCbor.decodeIssuerSigned(issuerSigned);
+  return await IssuerSignedFromString.parseAsync(decodedIssuerSignedString);
+};

package/src/cbor/cbor/failure.ts

@@ -0,0 +1,18 @@
+/**
+ * All error codes that the module could return.
+ */
+export type CborFailureCodes =
+  | 'UNABLE_TO_DECODE'
+  | 'INVALID_ENCODING'
+  | 'UNKNOWN_EXCEPTION';
+
+/**
+ * Error type returned by a rejected promise.
+ *
+ * If additional error information are available,
+ * they are stored in the {@link CborFailure["userInfo"]} field.
+ */
+export type CborFailure = {
+  message: CborFailureCodes;
+  userInfo: Record<string, string>;
+};

package/src/cbor/cbor/index.ts

@@ -0,0 +1,9 @@
+export { decode, decodeDocuments, decodeIssuerSigned } from './decoder';
+export {
+  DocumentValue,
+  Documents,
+  DocumentsFromString,
+  IssuerSigned,
+  MDOC,
+} from './schema';
+export { type CborFailure, type CborFailureCodes } from './failure';

package/src/cbor/cbor/schema.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { coerceToJSON } from './schema.utils';
+
+export enum DocumentTypeEnum {
+  MDL = 'org.iso.18013.5.1.mDL',
+  EU_PID = 'eu.europa.ec.eudi.pid.1',
+}
+
+export const DocumentType = z.nativeEnum(DocumentTypeEnum);
+export type DocumentType = z.infer<typeof DocumentType>;
+
+/**
+ * Value contained in a document
+ */
+export const DocumentValue = z.object({
+  digestID: z.coerce.number().optional(),
+  random: z.string().optional(),
+  elementIdentifier: z.string(),
+  elementValue: z.any(),
+});
+
+export type DocumentValue = z.infer<typeof DocumentValue>;
+
+/**
+ * Issuer Auth Unprotected Header Entry
+ */
+export const IssuerAuthUnprotectedHeader = z.object({
+  algorithm: z.coerce.string().optional(),
+  keyId: z.string().optional(),
+  x5chain: z.array(z.string()).optional(),
+});
+
+export type IssuerAuthUnprotectedHeader = z.infer<
+  typeof IssuerAuthUnprotectedHeader
+>;
+
+/**
+ * Issuer Auth Payload Validity Info
+ */
+export const IssuerAuthPayloadValidityInfo = z.object({
+  signed: z.coerce.date(),
+  validUntil: z.coerce.date(),
+  validFrom: z.coerce.date(),
+  expectedUpdate: z.coerce.date().optional(),
+});
+
+export type IssuerAuthPayloadValidityInfo = z.infer<
+  typeof IssuerAuthPayloadValidityInfo
+>;
+
+/**
+ * EC KEY
+ */
+const ECKey = z.object({
+  kty: z.enum(['EC']),
+  crv: z.enum(['P-256', 'P-384', 'P-521']),
+  x: z.string(),
+  y: z.string(),
+});
+
+/**
+ * RSA KEY
+ */
+const RSAKEY = z.object({
+  kty: z.enum(['RSA']),
+  alg: z.string(),
+  e: z.string(),
+  n: z.string(),
+});
+
+const PublicKey = z.union([RSAKEY, ECKey]);
+
+/**
+ * Issuer Auth Payload Device Key Info
+ */
+export const IssuerAuthPayloadDeviceKeyInfo = z.object({
+  deviceKey: PublicKey,
+});
+
+export type IssuerAuthPayloadDeviceKeyInfo = z.infer<
+  typeof IssuerAuthPayloadDeviceKeyInfo
+>;
+
+/**
+ * Issuer Auth Payload Object
+ */
+export const IssuerAuthPayload = z.object({
+  docType: z.string().optional(),
+  version: z.string().optional(),
+  validityInfo: IssuerAuthPayloadValidityInfo,
+  digestAlgorithm: z.string().optional(),
+  deviceKeyInfo: IssuerAuthPayloadDeviceKeyInfo,
+  valueDigests: z.record(z.any()),
+});
+
+export type IssuerAuthPayload = z.infer<typeof IssuerAuthPayload>;
+
+/**
+ * Issuer Auth Object
+ */
+export const IssuerAuth = z.object({
+  rawValue: z.string().optional(),
+  protectedHeader: z.string().optional(),
+  unprotectedHeader: IssuerAuthUnprotectedHeader,
+  payload: IssuerAuthPayload,
+  signature: z.string().optional(),
+});
+
+export type IssuerAuth = z.infer<typeof IssuerAuth>;
+
+/**
+ * Issuer signed object
+ */
+export const IssuerSigned = z.object({
+  nameSpaces: z.record(z.string(), coerceToJSON.pipe(z.array(DocumentValue))),
+  issuerAuth: IssuerAuth,
+});
+
+export type IssuerSigned = z.infer<typeof IssuerSigned>;
+
+/**
+ * mDOC object
+ */
+export const MDOC = z.object({
+  docType: DocumentType,
+  issuerSigned: IssuerSigned,
+});
+
+export type MDOC = z.infer<typeof MDOC>;
+
+/**
+ * CBOR decoded data containing the status, version and the list of documents
+ */
+export const Documents = z.object({
+  status: z.number().optional(),
+  version: z.string().optional(),
+  documents: coerceToJSON.pipe(z.array(MDOC)),
+});
+
+/**
+ * Documents object from string
+ */
+export const DocumentsFromString = coerceToJSON.pipe(Documents);
+
+/**
+ * IssuerSigned object from string
+ */
+export const IssuerSignedFromString = coerceToJSON.pipe(IssuerSigned);
+
+export type Documents = z.infer<typeof Documents>;

package/src/cbor/cbor/schema.utils.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+
+/**
+ * If the value is a string, parse it as JSON.
+ * Otherwise, return the value as is.
+ * Useful for unescaping stringified JSON content
+ */
+export const coerceToJSON = z.any().transform((any) => {
+  if (typeof any === 'object') {
+    return any;
+  }
+  return JSON.parse(any);
+});

package/src/cbor/cose/README.md

@@ -0,0 +1,53 @@
+## COSE
+
+This module provides methods to sign and verify data with COSE.
+
+```typescript
+import { COSE } from '@pagopa/io-react-native-cbor';
+```
+
+### Methods
+
+#### `sign`
+
+Signs base64 encoded data using COSE (CBOR Object Signing and Encryption).
+Returns a `Promise` which resolves to a `string` containing the COSE-Sign1 object in base64 encoding or rejects with an instance of `CoseFailure` in case of failures.
+
+```typescript
+try {
+  const coseSign1 = await COSE.sign('base64EncodedData', 'keyTag');
+} catch (e) {
+  const { message, userInfo } = e as CoseFailure;
+}
+```
+
+#### `verify`
+
+Verifies a COSE-Sign1 object using the provided public key.
+Returns a `Promise` which resolves to a `boolean` indicating if the signature is valid or rejects with an instance of `CoseFailure` in case of failures.
+
+```typescript
+// public key in JWK format
+const publicKey = {
+  kty: 'EC',
+  crv: 'P-256',
+  x: '...',
+  y: '...',
+};
+
+try {
+  const isValid = await COSE.verify('coseSign1Base64Data', publicKey);
+} catch (e) {
+  const { message, userInfo } = e as CoseFailure;
+}
+```
+
+### Error Codes
+
+| Type                 | Platform    | Description                                        |
+| -------------------- | ----------- | -------------------------------------------------- |
+| PUBLIC_KEY_NOT_FOUND | Android/iOS | The public key is missing for the specified keyTag |
+| INVALID_ENCODING     | Android/iOS | Provided payload has incorrect encoding            |
+| UNABLE_TO_SIGN       | Android/iOS | It was not possible to sign the given string       |
+| THREADING_ERROR      | iOS         | Unexpected failure                                 |
+| UNKNOWN_EXCEPTION    | Android/iOS | Unexpected failure                                 |

package/src/cbor/cose/failure.ts

@@ -0,0 +1,20 @@
+/**
+ * All error codes that the module could return.
+ */
+export type CoseFailureCodes =
+  | 'PUBLIC_KEY_NOT_FOUND'
+  | 'UNABLE_TO_SIGN'
+  | 'INVALID_ENCODING'
+  | 'THREADING_ERROR'
+  | 'UNKNOWN_EXCEPTION';
+
+/**
+ * Error type returned by a rejected promise.
+ *
+ * If additional error information are available,
+ * they are stored in the {@link CoseError["userInfo"]} field.
+ */
+export type CoseFailure = {
+  message: CoseFailureCodes;
+  userInfo: Record<string, string>;
+};

package/src/cbor/cose/index.ts

@@ -0,0 +1,2 @@
+export { sign, verify } from './sign';
+export { type CoseFailure, type CoseFailureCodes } from './failure';

package/src/cbor/cose/sign.ts

@@ -0,0 +1,25 @@
+import type { PublicKey } from '@pagopa/io-react-native-crypto';
+import { IoReactNativeCbor } from '..';
+
+/**
+ * Sign base64 encoded data with COSE and return the COSE-Sign1 object in base64 encoding
+ *
+ * @param payload - The base64 or base64url encoded payload to sign
+ * @param keyTag - The alias of the key to use for signing.
+ * @throws {CoseFailure} If the key does not exist
+ * @returns The COSE-Sign1 object in base64 encoding
+ */
+export const sign = async (payload: string, keyTag: string): Promise<string> =>
+  await IoReactNativeCbor.sign(payload, keyTag);
+
+/**
+ * Verifies a COSE-Sign1 object with the provided public key
+ *
+ * @param data - The COSE-Sign1 object in base64 or base64url encoding
+ * @param publicKey - The public key in JWK format
+ * @returns true if the signature is valid, false otherwise
+ */
+export const verify = async (
+  data: string,
+  publicKey: PublicKey
+): Promise<boolean> => await IoReactNativeCbor.verify(data, publicKey);

package/src/cbor/index.ts

@@ -0,0 +1,18 @@
+import { NativeModules, Platform } from 'react-native';
+
+const LINKING_ERROR =
+  `The package '@pagopa/io-react-native-cbor' doesn't seem to be linked. Make sure: \n\n` +
+  Platform.select({ ios: "- You have run 'pod install'\n", default: '' }) +
+  '- You rebuilt the app after installing the package\n' +
+  '- You are not using Expo Go\n';
+
+export const IoReactNativeCbor = NativeModules.IoReactNativeCbor
+  ? NativeModules.IoReactNativeCbor
+  : new Proxy(
+      {},
+      {
+        get() {
+          throw new Error(LINKING_ERROR);
+        },
+      }
+    );

package/src/index.tsx

@@ -0,0 +1,5 @@
+import * as CBOR from './cbor/cbor';
+import * as COSE from './cbor/cose';
+import * as ISO18013_5 from './iso18013/iso18013-5';
+import * as ISO18013_7 from './iso18013/iso18013-7';
+export { CBOR, COSE, ISO18013_5, ISO18013_7 };

package/src/iso18013/index.ts

@@ -0,0 +1,25 @@
+import { NativeModules, Platform } from 'react-native';
+export {
+  type AcceptedFields,
+  type EventError,
+  type VerifierRequest,
+  parseEventError,
+  parseVerifierRequest,
+} from './iso18013-5/schema';
+
+const LINKING_ERROR =
+  `The package '@pagopa/io-react-native-proximity' doesn't seem to be linked. Make sure: \n\n` +
+  Platform.select({ ios: "- You have run 'pod install'\n", default: '' }) +
+  '- You rebuilt the app after installing the package\n' +
+  '- You are not using Expo Go\n';
+
+export const IoReactNativeProximity = NativeModules.IoReactNativeIso18013
+  ? NativeModules.IoReactNativeIso18013
+  : new Proxy(
+      {},
+      {
+        get() {
+          throw new Error(LINKING_ERROR);
+        },
+      }
+    );

package/src/iso18013/iso18013-5/README.md

@@ -0,0 +1,234 @@
+# ISO18013-5
+
+This library provides a React Native module based on [iso18013-android](https://github.com/pagopa/iso18013-android) and [iso18013-ios](https://github.com/pagopa/iso18013-ios) which allows mDL proximity presentation according to the
+ISO 18013-5 standard and remote presentation according to the ISO 18013-7 standard.
+
+## Installation
+
+## Usage
+
+### `events`
+
+This library emits the following events:
+| Event | Payload | Description |
+|---------------------------|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| onDeviceConnecting (iOS only) | `undefined` | Event dispatched when the verifier app is connecting |
+| onDeviceConnected | `undefined` | Event dispatched when the verifier app is connected. |
+| onDocumentRequestReceived | `{ data: string } \| undefined` | Event dispatched when the consumer app receives a new request, contained in the data payload. It can be parsed via the `parseVerifierRequest` provided [here](src/schema.ts). |
+| onDeviceDisconnected | `undefined` | Event dispatched when the verifier app disconnects. |
+| onError | `{ error: string } \| undefined` | Event dispatched when an error occurs which is contained in the error payload. It can be parsed via the `parseError` provided [here](src/schema.ts). |
+
+Listeners can be added using the `addListener` method and removed using the `removeListener` method.
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+ISO18013_5.addListener('event', () => console.log('event occurred'));
+
+ISO18013_5.removeListener('event');
+```
+
+#### `onDeviceConnecting`
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+ISO18013_5.addListener('onDeviceConnecting', () => {
+  console.log('Device is connecting');
+});
+```
+
+#### `onDeviceConnected`
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+ISO18013_5.addListener('onDeviceConnected', () => {
+  console.log('Device is connected');
+});
+```
+
+#### `onDocumentRequestReceived`
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+ISO18013_5.addListener(
+  'onDocumentRequestReceived',
+  (payload: ISO18013_5.EventsPayload['onDocumentRequestReceived']) => {
+    console.log('onDocumentRequestReceived', payload);
+    if (!payload || !payload.data) {
+      console.warn('Request does not contain a message.');
+      return;
+    }
+
+    // Parse and verify the received request with the exposed function
+    const parsedJson = JSON.parse(payload.data);
+    console.log('Parsed JSON:', parsedJson);
+    const parsedResponse = parseVerifierRequest(parsedJson);
+    console.log('Parsed response:', JSON.stringify(parsedResponse));
+  }
+);
+```
+
+#### `onDeviceDisconnected`
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+ISO18013_5.addListener('onDeviceDisconnected', () => {
+  console.log('Device is disconnected');
+});
+```
+
+#### `onError`
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+ISO18013_5.addListener(
+  'onError',
+  async (data: ISO18013_5.EventsPayload['onError']) => {
+    try {
+      if (!data || !data.error) {
+        throw new Error('No error data received');
+      }
+      const parsedError = parseError(data.error);
+      console.error(`onError: ${parsedError}`);
+    } catch (e) {
+      console.error('Error parsing onError data:', e);
+    } finally {
+      // Close the flow on error
+      await closeFlow();
+    }
+  }
+);
+```
+
+### `start`
+
+Starts the proximity flow and starts the bluetooth service. This method also accepts optional parameters to configure the initialization on Android, along with the possibility
+to specify a certificates of array to verify the reader app.
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+await ISO18013_5.start();
+```
+
+### `getQrCodeString`
+
+Returns the QR code string which contains a base64url encoded CBOR object which encodes the bluetooth engagement data.
+It can be used to display the QR code in the UI which will be scanned by the verifier app.
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+const qrCodeString = await ISO18013_5.getQrCodeString();
+console.log(qrCodeString);
+```
+
+### `generateResponse`
+
+Generates a response that will be sent to the verifier app containing the requested documents.
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+const response = await ISO18013_5.generateResponse({
+  documents: [
+    {
+      type: 'mDL',
+      data: 'base64url-encoded-data',
+    },
+  ],
+});
+console.log(response);
+```
+
+### `sendResponse`
+
+Sends the response generate by `generateResponse` to the verifier app.
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+await ISO18013_5.sendResponse(response);
+```
+
+### `sendErrorResponse`
+
+Sends an error response to the verifier app. The supported error codes are defined in the Table 20 of the ISO 18013-5 standard and are coded in the `ErrorCode` enum.
+
+```typescript
+import { ISO18013_5, ErrorCode } from '@pagopa/io-react-native-iso18013';
+
+await ISO18013_5.sendErrorResponse({
+  errorCode: ErrorCode.SESSION_ENCRYPTION,
+  errorMessage: 'An error occurred while encrypting the session',
+});
+```
+
+### `close`
+
+Closes the QR engagement by releasing the resources allocated during the `start` method.
+Before starting a new flow, it is necessary to call this method to ensure that the previous flow is properly closed.
+The listeners can be removed using the `removeListener` method.
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+
+await ISO18013_5.close();
+```
+
+## Proximity Flow Schema
+
+This section describes a high level overview of the interactions between an app implementing the `io-react-native-proximity` library and a verifier app.
+
+```mermaid
+sequenceDiagram
+    participant app as Consumer App
+    participant proximity as io-react-native-iso18013
+    participant verifier as Verifier App
+
+    Note over proximity, verifier: If an error occurs during the flow, the onError callback is triggered
+    app->>+proximity: Calls start()
+    app->>+proximity: Calls getQrCode()
+    proximity-->>+app: QR code string
+    app->>+app: Renders the QR code string
+    verifier->>+app: Scans the QR code
+    proximity->>+app: Triggers the onDeviceConnecting callback
+    verifier->>+app: Connects to the verifier app
+    proximity->>+app: Triggers the onDeviceConnected callback
+    verifier->>+app: Requests the credential(s)
+    proximity->>+app: Triggers the onDocumentRequestReceived() callback
+    app->>+proximity: Parses the request by calling parseVerifierRequest()
+    proximity-->>+app: Returns a VerifierRequest
+    app->>+app: Shows the requested data and asks for user consent
+    alt The user accepts
+        app->>+proximity: Calls generateResponse()
+        proximity-->>+app: Returns the response
+        app->>+proximity: Calls sendResponse()
+        proximity->>+verifier: Sends the response
+        verifier->>+verifier: Shows the received credential(s) and the verification result
+    else The user rejects
+        app->>+proximity: Calls sendErrorResponse()
+        proximity->>+verifier: Sends the error response code
+        verifier->>+verifier: Shows the received error response code
+    end
+    verifier->>+app: Closes the connection
+    proximity->>+app: Calls the onDeviceDisconnected callback
+```
+
+## Error Codes
+
+| Type                            | Platform    | Description                                                                  |
+| ------------------------------- | ----------- | ---------------------------------------------------------------------------- |
+| DRH_NOT_DEFINED                 | Android     | The device retrieval helper hasn't been initialized, call the `start` method |
+| QR_ENGAGEMENT_NOT_DEFINED_ERROR | Android     | The QR engagement hasn't been initialized, call the `start` method           |
+| START_ERROR                     | Android/iOS | An error occurred while initializing the required resources                  |
+| GET_QR_CODE_ERROR               | Android/iOS | An error occurred while generating the engagement QR code                    |
+| GENERATE_RESPONSE_ERROR         | Android/iOS | An error occurred while generating the response for the verifier app         |
+| SEND_RESPONSE_ERROR             | Android/iOS | An error occurred while sending the response to the verifier app             |
+| SEND_ERROR_RESPONSE_ERROR       | Android/iOS | An error occurred while sending the error response to the verifier app       |
+| CLOSE_ERROR                     | Android     | An error occured while closing the required resources                        |

package/src/iso18013/iso18013-5/index.ts

@@ -0,0 +1,23 @@
+export {
+  type AcceptedFields,
+  type EventError,
+  type VerifierRequest,
+  parseEventError,
+  parseVerifierRequest,
+} from './schema';
+
+export {
+  ErrorCode,
+  type Events,
+  type EventsPayload,
+  addListener,
+  close,
+  generateResponse,
+  getQrCodeString,
+  removeListener,
+  sendErrorResponse,
+  sendResponse,
+  start,
+} from './proximity';
+
+export { type RequestedDocument } from '../types';