feat(IT-Wallet): [SIW-3045] Add L2+ PID issuance flow with MRTD PoP (#7647)

## Short description
This PR introduces the L2+ flow for IT-Wallet. L2+ adds an extra step
after the primary SPID or CieID identification, requiring the user to
complete an MRTD (ID card) proof-of-possession check.
The verification is performed through an NFC scan of the ID card.

This PR also includes a major refactoring of the CIE scan logic, making
it reusable and shareable across both the CIE+PIN and MRTD flows.

## List of changes proposed in this pull request
### Credential Issuance Flow & Proof Handling

* Added support for selecting proof type (`mrtd-pop` or `none`) during
credential issuance, controlled by the new `withMRTDPoP` parameter in
`startAuthFlow`, and updated related function signatures and logic in
`itwIssuanceUtils.ts`.
[[1]](diffhunk://#diff-2cd6d88d7a0a5ffab205730094379c0e1c542e964874a0edf5a5d60416e295c3R28)
[[2]](diffhunk://#diff-2cd6d88d7a0a5ffab205730094379c0e1c542e964874a0edf5a5d60416e295c3R39-L50)
[[3]](diffhunk://#diff-2cd6d88d7a0a5ffab205730094379c0e1c542e964874a0edf5a5d60416e295c3R67-R69)
* Improved validation in `getCredentialIdentifierFromAccessToken` to
throw an error for unsupported authorization detail types, increasing
robustness.

### MRTD PoP Challenge Utilities

* Introduced the `mrtd.ts` utility with functions for initializing and
validating MRTD PoP challenges, encapsulating cryptographic context
management and challenge handling.

### NFC Feature Detection & L3 Flow

* Simplified L3 feature detection by checking for `level === "l3"`
directly instead of using a helper, and updated related tests and
screens to reflect this logic.
[[1]](diffhunk://#diff-aac82824191e7fddf4b8b79ddee9b8b13896340cea331ff4f4f2e6ea90335170L31-R30)
[[2]](diffhunk://#diff-ad0b45dc86f8c2a0249744d4413aef7b7d8667579124c2c7d156067e8c474304L21-R35)
* Updated the discovery component to use wallet lifecycle validity for
determining whether to start in "upgrade" or "issuance" mode, improving
flow control.

### Localization & Dependency Updates

* Updated Italian localization strings for credential issuance modes to
clarify durations and hints.
* Upgraded the `@pagopa/io-react-native-wallet` dependency to version
2.4.0 for access to new features and bug fixes.

### Error Handling & Analytics

* Refactored the CIE card read failure content to improve error
tracking, analytics integration, and retry handling, making the
component more robust and customizable.
[[1]](diffhunk://#diff-9c4c2ef6526484c9cf6023ef5875cd7d05a72c0a0bc331bb30305c47f1fafee8L2-R65)
[[2]](diffhunk://#diff-4f759b936530a9db89be53e8df2c20c5e69713067abb07ce762fce6d0dcc64ddL227-R229)

## How to test

- With the IT-Wallet whitelist flag **disabled**:
- Verify that all identification methods (CIE+PIN, SPID, CieID) behave
as before and no regressions are introduced.
- With the IT-Wallet whitelist flag **enabled**:
- Verify that the CIE+PIN identification flow still works correctly and
without regressions.
- Verify that it is possible to obtain an L3 PID using SPID or CieID
through the MRTD PoP flow.

## Demo

| SPID + CIE | CieID + CIE |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/83e7bf7b-7c60-4b21-9d7c-01175c00c395"
/> | <video
src="https://github.com/user-attachments/assets/f72e8343-0905-4f0b-bff4-99cdb880bc37"
/> |

---------

Co-authored-by: Alessandro Mazzon <[email protected]>

Author: mastro993

locales/it/index.json

@@ -4749,27 +4749,24 @@
           "mode": {
             "ciePin": {
               "title": "Continua con CIE + PIN",
-              "subtitle": {
-                "default": "Dovrai usare la Carta di Identità Elettronica (CIE) e inserire il suo PIN di 8 cifre.",
-                "l3-next": "Ha una durata di 12 mesi"
-              },
+              "subtitle": "Ha una durata di 12 mesi",
               "badge": "scelta consigliata"
             },
             "cieId": {
               "title": "Continua con l’app CieID",
               "subtitle": {
                 "default": "Dovrai usare credenziali e app CieID",
-                "l3-next": "Ha una durata di 12 mesi"
+                "l3": "Ha una durata di 12 mesi"
               }
             },
             "spid": {
               "title": {
                 "default": "Continua con SPID",
-                "l3-next": "Continua con SPID + CIE"
+                "l3": "Continua con SPID + CIE"
               },
               "subtitle": {
                 "default": "Dovrai usare credenziali e app (o SMS)",
-                "l3-next": "Ha una durata di 90 giorni"
+                "l3": "Ha una durata di 90 giorni"
               }
             }
           }

package.json

@@ -69,7 +69,7 @@
     "@pagopa/io-react-native-jwt": "^2.1.0",
     "@pagopa/io-react-native-login-utils": "^1.1.0",
     "@pagopa/io-react-native-secure-storage": "^0.2.1",
-    "@pagopa/io-react-native-wallet": "^2.3.0",
+    "@pagopa/io-react-native-wallet": "^2.4.0",
     "@pagopa/io-react-native-wallet-legacy": "npm:@pagopa/[email protected]",
     "@pagopa/io-react-native-zendesk": "^0.3.30",
     "@pagopa/react-native-cie": "^1.4.3",

ts/features/common/components/cie/CieCardReadContent.tsx

@@ -232,7 +232,9 @@ const ContentAndroid = (props: CieCardReadContentProps) => (
 );
 
 /**
- * Renders the read progress screen content based on the platform
+ * Renders the read progress screen content based on the platform.
+ * It is fully customizable via props and it is used as base component to display the
+ * reading, failure and success states for the CIE manager flow.
  */
 export const CieCardReadContent = platformSelect({
   ios: ContentIos,

ts/features/common/utils/cie/__tests__/index.ts

@@ -59,6 +59,7 @@ export const requestCredential = async ({
     await Credential.Issuance.startUserAuthorization(
       issuerConf,
       credentialIds,
+      { proofType: "none" },
       {
         walletInstanceAttestation,
         redirectUri: env.ISSUANCE_REDIRECT_URI,

ts/features/itwallet/common/utils/itwCredentialIssuanceUtils.ts

@@ -147,7 +147,10 @@ export const isItwCredential = ({
   return pipe(
     O.tryCatch(getVerificationByFormat[format as CredentialFormat]),
     O.chain(O.fromNullable),
-    O.chainNullableK(({ assurance_level }) => assurance_level === "high"),
+    O.chainNullableK(
+      ({ assurance_level, trust_framework }) =>
+        assurance_level === "high" || trust_framework === "it_l2+document_proof"
+    ),
     O.getOrElse(() => false)
   );
 };

ts/features/itwallet/common/utils/itwCredentialUtils.ts

@@ -25,6 +25,7 @@ type StartAuthFlowParams = {
   env: Env;
   walletAttestation: string;
   identification: IdentificationContext;
+  withMRTDPoP: boolean;
 };
 
 /**
@@ -35,19 +36,20 @@ type StartAuthFlowParams = {
  * @param env - The environment to use for the wallet provider base URL
  * @param walletAttestation - The wallet attestation.
  * @param identification - The identification context.
+ * @param withMRTDPoP - Whether to use MRTD PoP proof or not.
  * @returns Authentication params to use when completing the flow.
  */
 const startAuthFlow = async ({
   env,
   walletAttestation,
-  identification
+  identification,
+  withMRTDPoP
 }: StartAuthFlowParams) => {
   const startFlow: Credential.Issuance.StartFlow = () => ({
     issuerUrl: env.WALLET_PID_PROVIDER_BASE_URL,
     credentialId: "dc_sd_jwt_PersonIdentificationData"
   });
 
-  // When issuing an L3 PID, we should not provide an IDP hint
   const idpHint = getIdpHint(identification, env);
 
   const { issuerUrl, credentialId } = startFlow();
@@ -62,6 +64,9 @@ const startAuthFlow = async ({
     await Credential.Issuance.startUserAuthorization(
       issuerConf,
       [credentialId],
+      withMRTDPoP
+        ? { proofType: "mrtd-pop", idpHinting: idpHint }
+        : { proofType: "none" },
       {
         walletInstanceAttestation: walletAttestation,
         redirectUri: env.ISSUANCE_REDIRECT_URI,
@@ -218,6 +223,12 @@ function getCredentialIdentifierFromAccessToken(
   accessToken: CredentialAccessToken,
   authorizationDetail: AuthorizationDetail
 ) {
+  if (authorizationDetail.type !== "openid_credential") {
+    throw new Error(
+      `Unsupported authorization detail type: ${authorizationDetail.type}`
+    );
+  }
+
   const accessTokenAuthDetail = accessToken.authorization_details.find(
     authDetails =>
       authDetails.credential_configuration_id ===
@@ -275,11 +286,6 @@ const SPID_IDP_HINTS: { [key: string]: string } = {
  * @param isL3 flag that indicates that we need to issue an L3 PID
  */
 export const getIdpHint = (idCtx: IdentificationContext, env: Env) => {
-  if (idCtx.level === "L3") {
-    // When issuing an L3 PID, we should not provide an IDP hint
-    return undefined;
-  }
-
   const isSpidMode = idCtx.mode === "spid";
 
   if (env.type === "pre") {

ts/features/itwallet/common/utils/itwIssuanceUtils.ts

@@ -0,0 +1,104 @@
+import {
+  createCryptoContextFor,
+  Credential
+} from "@pagopa/io-react-native-wallet";
+import { WIA_KEYTAG } from "./itwCryptoContextUtils";
+import { IssuerConfiguration } from "./itwTypesUtils";
+
+export type InitMrtdPoPChallengeParams = {
+  issuerConf: IssuerConfiguration;
+  walletInstanceAttestation: string;
+  authRedirectUrl: string;
+};
+
+export type ValidateMrtdPoPChallengeParams = {
+  issuerConf: IssuerConfiguration;
+  walletInstanceAttestation: string;
+  validationUrl: string;
+  mrtd_auth_session: string;
+  mrtd_pop_nonce: string;
+  mrtd: Credential.Issuance.MRTDPoP.MrtdPayload;
+  ias: Credential.Issuance.MRTDPoP.IasPayload;
+};
+
+export const initMrtdPoPChallenge = async ({
+  authRedirectUrl,
+  issuerConf,
+  walletInstanceAttestation
+}: InitMrtdPoPChallengeParams) => {
+  const wiaCryptoContext = createCryptoContextFor(WIA_KEYTAG);
+
+  const { challenge_info } =
+    await Credential.Issuance.continueUserAuthorizationWithMRTDPoPChallenge(
+      authRedirectUrl
+    );
+
+  const {
+    htu: initUrl,
+    mrtd_auth_session,
+    mrtd_pop_jwt_nonce
+  } = await Credential.Issuance.MRTDPoP.verifyAndParseChallengeInfo(
+    issuerConf,
+    challenge_info,
+    { wiaCryptoContext }
+  );
+
+  const {
+    htu: validationUrl,
+    challenge,
+    mrtd_pop_nonce
+  } = await Credential.Issuance.MRTDPoP.initChallenge(
+    issuerConf,
+    initUrl,
+    mrtd_auth_session,
+    mrtd_pop_jwt_nonce,
+    {
+      walletInstanceAttestation,
+      wiaCryptoContext
+    }
+  );
+
+  return {
+    challenge,
+    mrtd_auth_session,
+    mrtd_pop_nonce,
+    validationUrl
+  };
+};
+
+export const validateMrtdPoPChallenge = async ({
+  validationUrl,
+  mrtd_auth_session,
+  mrtd_pop_nonce,
+  issuerConf,
+  walletInstanceAttestation,
+  ias,
+  mrtd
+}: ValidateMrtdPoPChallengeParams) => {
+  const wiaCryptoContext = createCryptoContextFor(WIA_KEYTAG);
+
+  const { mrtd_val_pop_nonce, redirect_uri } =
+    await Credential.Issuance.MRTDPoP.validateChallenge(
+      issuerConf,
+      validationUrl,
+      mrtd_auth_session,
+      mrtd_pop_nonce,
+      mrtd,
+      ias,
+      {
+        walletInstanceAttestation,
+        wiaCryptoContext
+      }
+    );
+
+  const { callbackUrl } =
+    await Credential.Issuance.MRTDPoP.buildChallengeCallbackUrl(
+      redirect_uri,
+      mrtd_val_pop_nonce,
+      mrtd_auth_session
+    );
+
+  return {
+    callbackUrl
+  };
+};

ts/features/itwallet/common/utils/mrtd.ts

@@ -46,6 +46,7 @@ import {
 import { useItwDismissalDialog } from "../../common/hooks/useItwDismissalDialog.tsx";
 import { itwIsActivationDisabledSelector } from "../../common/store/selectors/remoteConfig.ts";
 import { generateItwIOMarkdownRules } from "../../common/utils/markdown.tsx";
+import { itwLifecycleIsValidSelector } from "../../lifecycle/store/selectors/index.ts";
 import { ItwEidIssuanceMachineContext } from "../../machine/eid/provider.tsx";
 import { selectIsLoading } from "../../machine/eid/selectors.ts";
 
@@ -63,16 +64,17 @@ export const ItwDiscoveryInfoComponent = () => {
   const isLoading = ItwEidIssuanceMachineContext.useSelector(selectIsLoading);
   const itwActivationDisabled = useIOSelector(itwIsActivationDisabledSelector);
   const { tos_url } = useIOSelector(tosConfigSelector);
+  const isWalletValid = useIOSelector(itwLifecycleIsValidSelector);
   const toast = useIOToast();
 
   useOnFirstRender(
     useCallback(() => {
       machineRef.send({
         type: "start",
-        mode: "issuance",
+        mode: isWalletValid ? "upgrade" : "issuance",
         level: "l3"
       });
-    }, [machineRef])
+    }, [machineRef, isWalletValid])
   );
 
   const dismissalDialog = useItwDismissalDialog({

ts/features/itwallet/discovery/components/ItwDiscoveryInfoComponent.tsx

@@ -2,7 +2,6 @@ import { IOStackNavigationRouteProps } from "../../../../navigation/params/AppPa
 import { useIOSelector } from "../../../../store/hooks.ts";
 import { itwHasNfcFeatureSelector } from "../../identification/common/store/selectors/index.ts";
 import { EidIssuanceLevel } from "../../machine/eid/context.ts";
-import { isL3IssuanceFeaturesEnabled } from "../../machine/eid/utils.ts";
 import { ItwParamsList } from "../../navigation/ItwParamsList.ts";
 import { ItwDiscoveryInfoComponent } from "../components/ItwDiscoveryInfoComponent.tsx";
 import { ItwDiscoveryInfoFallbackComponent } from "../components/ItwDiscoveryInfoFallbackComponent.tsx";
@@ -28,7 +27,7 @@ export const ItwDiscoveryInfoScreen = ({
   const { level = "l2" } = route.params ?? {};
   const hasNfcFeature = useIOSelector(itwHasNfcFeatureSelector);
 
-  if (isL3IssuanceFeaturesEnabled(level)) {
+  if (level === "l3") {
     if (!hasNfcFeature) {
       // L3 requires NFC, show not supported screen
       return <ItwNfcNotSupportedComponent />;