@pagopa/io-react-native-iso18013 0.1.0

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

@@ -0,0 +1,134 @@
+import { NativeEventEmitter, Platform } from 'react-native';
+import { IoReactNativeProximity } from '..';
+import type { AcceptedFields } from './schema';
+import type { RequestedDocument } from '../types';
+
+const eventEmitter = new NativeEventEmitter(IoReactNativeProximity);
+
+/**
+ * Events emitted by the native module:
+ * - `onDeviceConnecting`: (iOS only) Emitted when the device is connecting to the verifier app.
+ * - `onDeviceConnected`: Emitted when the device is connected to the verifier app.
+ * - `onDocumentRequestReceived`: Emitted when a document request is received from the verifier app. Carries a payload containing the request data.
+ * - `onDeviceDisconnected`: Emitted when the device is disconnected from the verifier app.
+ * - `onError`: Emitted when an error occurs. Carries a payload containing the error data.
+ */
+export type EventsPayload = {
+  onDeviceConnecting: undefined;
+  onDeviceConnected: undefined;
+  // The message payload is a JSON string that can be parsed into a `VerifierRequest` structure via `parseVerifierRequest`.
+  onDocumentRequestReceived: { data?: string } | undefined;
+  onDeviceDisconnected: undefined;
+  onError: { error?: string } | undefined;
+};
+
+/**
+ * Events emitted by the native module.
+ */
+export type Events = keyof EventsPayload;
+
+/**
+ * Error codes that can be used with the `sendErrorResponse` method.
+ * These are defined based on the SessionData status code defined in the table 20 of the ISO 18013-5 standard
+ * and mirror codes defined in the native module.
+ */
+export enum ErrorCode {
+  SESSION_ENCRYPTION = 10,
+  CBOR_DECODING = 11,
+  SESSION_TERMINATED = 20,
+}
+
+/**
+ * Starts the proximity flow by allocating the necessary resources and initializing the Bluetooth stack.
+ * @param config.peripheralMode (Android only) - Whether the device is in peripheral mode. Defaults to true
+ * @param config.centralClientMode (Android only) - Whether the device is in central client mode. Defaults to false
+ * @param config.clearBleCache (Android only) - Whether the BLE cache should be cleared. Defaults to true
+ * @param config.certificates - Array of base64 representing DER encoded X.509 certificate which are used to authenticate the verifier app
+ */
+export function start(
+  config: {
+    peripheralMode?: boolean;
+    centralClientMode?: boolean;
+    clearBleCache?: boolean;
+    certificates?: string[];
+  } = {}
+): Promise<boolean> {
+  const { peripheralMode, centralClientMode, clearBleCache, certificates } =
+    config;
+  if (Platform.OS === 'ios') {
+    return IoReactNativeProximity.start(certificates ? certificates : []);
+  } else {
+    return IoReactNativeProximity.start(
+      peripheralMode ? peripheralMode : true,
+      centralClientMode ? centralClientMode : false,
+      clearBleCache ? clearBleCache : true,
+      certificates ? certificates : []
+    );
+  }
+}
+
+/**
+ * Gets the QR code string this method is responsible for initializing the connection and retrieving the QR code string
+ */
+export function getQrCodeString(): Promise<string> {
+  return IoReactNativeProximity.getQrCodeString();
+}
+
+/**
+ * Closes the QR engagement
+ */
+export function close(): Promise<boolean> {
+  return IoReactNativeProximity.close();
+}
+
+/**
+ * Sends an error response to the verifier app.
+ * The error code must be one of the `ErrorCode` enum values.
+ * @param code - The error code to be sent to the verifier app.
+ */
+export function sendErrorResponse(code: ErrorCode): Promise<boolean> {
+  return IoReactNativeProximity.sendErrorResponse(code);
+}
+
+/**
+ * Generates a response that will be sent to the verifier app containing the requested data
+ * @param documents - An array of `Document` which contains the requested data received from the `onDocumentRequestReceived` event
+ * @param acceptedFields - The accepted fields which will be presented to the verifier app. See the type definition for more details.
+ * @returns A base64 encoded response to be sent to the verifier app via `sendResponse`
+ */
+export function generateResponse(
+  documents: Array<RequestedDocument>,
+  acceptedFields: AcceptedFields
+): Promise<string> {
+  return IoReactNativeProximity.generateResponse(documents, acceptedFields);
+}
+
+/**
+ * Sends the response generated through the `generateResponse` method to the verifier app.
+ * Currently there's not evidence of the verifier app responding to this request, thus we don't handle the response.
+ * @param response - The base64 encoded response to be sent to the verifier app.
+ */
+export function sendResponse(response: string): Promise<boolean> {
+  return IoReactNativeProximity.sendResponse(response);
+}
+
+/**
+ * Adds a listener for a `QrEngagementEvents` event which will be emitted by the native module.
+ * The callback will be called with the event payload when the event is emitted.
+ * @param event - The event to listen for. The available events are defined in the `QrEngagementEvents` type.
+ * @param callback - The callback to be called when the event is emitted. The callback will receive the event payload as an argument.
+ */
+export function addListener<E extends Events>(
+  event: E,
+  callback: (data: EventsPayload[E]) => void
+) {
+  eventEmitter.addListener(event, callback);
+}
+
+/**
+ * Removes a listener for a `QrEngagementEvents` event.
+ * @param event - The event to remove the listener for. The available events are defined in the `QrEngagementEvents` type.
+ */
+export function removeListener(event: Events) {
+  eventEmitter.removeAllListeners(event);
+}

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

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+
+// Inner data: a record of booleans with the attributes and the intent to retain flag
+const booleanFieldGroup = z.record(z.boolean());
+
+const credentialEntrySchema = z
+  .object({
+    isAuthenticated: z.boolean(),
+  })
+  .catchall(booleanFieldGroup);
+
+const VerifierRequest = z.object({
+  request: z.record(credentialEntrySchema),
+});
+
+/**
+ * VerifierRequest type returned by the `onDocumentRequestReceived` event in `Events`.
+ * The outermost key represents the credential doctype, the inner key represents the namespace and the innermost key represents the requested fields with a boolean value
+ * indicating whether the verifier app wants to retain the field or not. The isAuthenticated field is present for each requested credentials and indicates wether or not the verifier is authenticated.
+ * Example:
+ *  `{
+ *    "org.iso.18013.5.1.mDL": {
+ *      "isAuthenticated": true,
+ *      "org.iso.18013.5.1": {
+ *        "hair_colour": true,
+ *        "given_name_national_character": true,
+ *        "family_name_national_character": true,
+ *        "given_name": true,
+ *      }
+ *    }
+ *  }`
+ * The request type can be also be used as input for the `generateResponse` method. The structure is the same, however the boolean value for each claim
+ * indicates the willing to present the claim.
+ */
+export type VerifierRequest = z.infer<typeof VerifierRequest>;
+
+/**
+ * Parses the input to a VerifierRequest object.
+ * This function is used to parse the request received from the verifier app.
+ * @param input - The input to be parsed
+ * @returns The parsed VerifierRequest object
+ */
+export const parseVerifierRequest = (input: unknown): VerifierRequest => {
+  return VerifierRequest.parse(input);
+};
+
+/**
+ * Zod schema for the type returned by the `onError` event in Proximity `Events`.
+ */
+const EventError = z.string().catch('Unknown error');
+
+/**
+ * Error type returned by the `onError` event in Proximity `Events`.
+ */
+export type EventError = z.infer<typeof EventError>;
+
+/**
+ * Parses the input to an Error object.
+ * This function is used to parse the error received from the verifier app via the `onError` event.
+ * @param input - The input to be parsed
+ * @returns The parsed Error object or a default error message if parsing fails
+ */
+export const parseEventError = (input: unknown): EventError => {
+  return EventError.parse(input);
+};
+
+/**
+ * This is the type definition for the accepted fields that will be presented to the verifier app.
+ * It contains of a nested object structure, where the outermost key represents the credential doctype.
+ * The inner dictionary contains namespaces, and for each namespace, there is another dictionary mapping requested claims to a boolean value,
+ * which indicates whether the user is willing to present the corresponding claim. Example:
+ * `{
+ *    "org.iso.18013.5.1.mDL": {
+ *      "org.iso.18013.5.1": {
+ *        "hair_colour": true, // Indicates the user is willing to present this claim
+ *        "given_name_national_character": true,
+ *        "family_name_national_character": true,
+ *        "given_name": true,
+ *     }
+ *    }
+ *  }`
+ **/
+export type AcceptedFields = {
+  [credential: string]: {
+    [namespace: string]: { [field: string]: boolean };
+  };
+};

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

@@ -0,0 +1,59 @@
+## ISO18013-7
+
+This module provides methods to obtain data structures necessary for the processes defined in the `ISO-18013` standard.
+
+```typescript
+import { ISO18013_7 } from '@pagopa/io-react-native-cbor';
+```
+
+### Methods
+
+#### `generateOID4VPDeviceResponse`
+
+Generates CBOR of the _Device Response_ containing all the claims that have been chosen to be presented during an _OID4VP_ session.
+
+Returns a `Promise` which resolves to a `string` containing the CBOR of the **Device Response** object or rejects with an instance of `CoseFailure` in case of failures.
+
+```typescript
+try {
+  const result = await ISO18013_7.generateOID4VPDeviceResponse(
+    clientId,
+    responseUri,
+    authorizationRequestNonce,
+    mdocGeneratedNonce,
+    documents,
+    fieldRequestedAndAccepted
+  );
+} catch (error: any) {
+  const { message, userInfo } = e as CoseFailure;
+}
+```
+
+#### Signature
+
+```typescript
+type RequestedDocument = {
+    issuerSignedContent : string,
+    alias : string,
+    docType : string
+}
+
+export const generateOID4VPDeviceResponse = async (
+  clientId: string,
+  responseUri: string,
+  authorizationRequestNonce: string,
+  mdocGeneratedNonce: string,
+  documents: Array<RequestedDocument>,
+  fieldRequestedAndAccepted: Record<string, any> | string
+) : Promise<string> => {...};
+```
+
+### Error Codes
+
+| Type                              | Platform    | Description                                                        |
+| --------------------------------- | ----------- | ------------------------------------------------------------------ |
+| UNABLE_TO_GENERATE_RESPONSE       | Android/iOS | Failure during the generation of a response                        |
+| DOC_REQUESTED_PARSING_EXCEPTION   | Android/iOS | The passed documents where in a bad format or contained wrong data |
+| REQUESTED_ITEMS_PARSING_EXCEPTION | iOS         | The passed items where in a bad format                             |
+| UNABLE_TO_GENERATE_TRANSCRIPT     | Android     | There has been an error generating the session transcript          |
+| UNKNOWN_EXCEPTION                 | Android/iOS | Unexpected failure                                                 |

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

@@ -0,0 +1,7 @@
+export {
+  generateOID4VPDeviceResponse,
+  type OID4VPFailure,
+  type OID4VPFailureCodes,
+} from './remote';
+
+export { type RequestedDocument } from '../types';

package/src/iso18013/iso18013-7/remote.ts

@@ -0,0 +1,54 @@
+import { IoReactNativeProximity } from '..';
+import type { RequestedDocument } from '../types';
+
+/**
+ * All error codes that the module could return.
+ */
+export type OID4VPFailureCodes =
+  | 'UNABLE_TO_GENERATE_RESPONSE'
+  | 'UNABLE_TO_GENERATE_TRANSCRIPT'
+  | 'INVALID_DOC_REQUESTED'
+  | 'GENERATE_OID4VP_DEVICE_RESPONSE_FAILED';
+
+/**
+ * Error type returned by a rejected promise.
+ *
+ * If additional error information are available,
+ * they are stored in the {@link OID4VPFailure["userInfo"]} field.
+ */
+export type OID4VPFailure = {
+  message: OID4VPFailureCodes;
+  userInfo: Record<string, string>;
+};
+
+/**
+ *
+ * @param clientId extracted from OID4VP session
+ * @param responseUri extracted from OID4VP session
+ * @param authorizationRequestNonce extracted from OID4VP session
+ * @param mdocGeneratedNonce To be generated
+ * @param documents An Array of {@link DocRequested}
+ * @param fieldRequestedAndAccepted extracted from OID4VP session, it's a record of claims
+ *                                  accepted for disclosure or its stringification
+ * @throws {OID4VPFailure} in case of failure
+ * @returns the Device Response in CBOR format
+ */
+export const generateOID4VPDeviceResponse = async (
+  clientId: string,
+  responseUri: string,
+  authorizationRequestNonce: string,
+  mdocGeneratedNonce: string,
+  documents: Array<RequestedDocument>,
+  fieldRequestedAndAccepted: Record<string, any> | string
+): Promise<string> => {
+  return await IoReactNativeProximity.generateOID4VPDeviceResponse(
+    clientId,
+    responseUri,
+    authorizationRequestNonce,
+    mdocGeneratedNonce,
+    documents,
+    typeof fieldRequestedAndAccepted === 'string'
+      ? fieldRequestedAndAccepted
+      : JSON.stringify(fieldRequestedAndAccepted)
+  );
+};

package/src/iso18013/types.ts

@@ -0,0 +1,16 @@
+/**
+ * Common types definition for ISO 18013-5 and ISO 18013-7 modules.
+ */
+
+/**
+ * Documents type to be used in the {@link generateResponse} for ISO18013-5 and {@link generateOID4VPDeviceResponse} for ISO18013-7.
+ * It contains:
+ * - issuerSignedContent which is a base64 or base64url encoded string representing the credential;
+ * - alias which is the alias of the key used to sign the credential;
+ * - docType which is the document type.
+ */
+export type RequestedDocument = {
+  issuerSignedContent: string;
+  alias: string;
+  docType: string;
+};