@pagopa/io-react-native-wallet 2.3.0 → 2.4.0

package/src/credential/issuance/mrtd-pop/03-validate-challenge.ts

@@ -0,0 +1,140 @@
+import { SignJWT, type CryptoContext } from "@pagopa/io-react-native-jwt";
+import { v4 as uuidv4 } from "uuid";
+import { IssuerResponseError } from "../../../utils/errors";
+import { hasStatusOrThrow, type Out } from "../../../utils/misc";
+import { createPopToken } from "../../../utils/pop";
+import * as WalletInstanceAttestation from "../../../wallet-instance-attestation";
+import type { EvaluateIssuerTrust } from "../../issuance";
+import {
+  MrtdPopVerificationResult,
+  type IasPayload,
+  type MrtdPayload,
+} from "./types";
+import type { VerifyAndParseChallengeInfo } from "./01-verify-and-parse-challenge-info";
+
+export type ValidateChallenge = (
+  issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
+  verifyUrl: string,
+  mrtd_auth_session: string,
+  mrtd_pop_nonce: string,
+  mrtd: MrtdPayload,
+  ias: IasPayload,
+  context: {
+    wiaCryptoContext: CryptoContext;
+    walletInstanceAttestation: string;
+    appFetch?: GlobalFetch["fetch"];
+  }
+) => Promise<MrtdPopVerificationResult>;
+
+export type BuildChallengeCallbackUrl = (
+  redirectUri: Out<ValidateChallenge>["redirect_uri"],
+  valPopNonce: Out<ValidateChallenge>["mrtd_val_pop_nonce"],
+  authSession: Out<VerifyAndParseChallengeInfo>["mrtd_auth_session"]
+) => Promise<{
+  callbackUrl: string;
+}>;
+
+/**
+ * Validates the MRTD signed challenge by sending the MRTD and IAS payloads to the issuer.
+ * This function must be called after {@link initChallenge} and after obtaining the MRTD and IAS payloads
+ * through the CIE PACE process.
+ *
+ * @param issuerConf - The issuer configuration containing the JWKS for signature verification.
+ * @param verifyUrl - The endpoint to call to validate the challenge.
+ * @param mrtd_auth_session - Session identifier for session binding obtained from the MRTD Proof JWT.
+ * @param mrtd_pop_nonce - Nonce value obtained from the MRTD Proof JWT.
+ * @param mrtd - MRTD validation data containing Data Groups and SOD.
+ * @param ias - IAS validation data containing Anti-Cloning Public Key, and SOD.
+ * @param context - The context containing the WIA crypto context used to retrieve the client public key,
+ * the wallet instance attestation and an optional fetch implementation.
+ * @returns The MRTD PoP Verification Result containing the validation nonce and redirect URI to complete the flow.
+ */
+export const validateChallenge: ValidateChallenge = async (
+  issuerConf,
+  verifyUrl,
+  mrtd_auth_session,
+  mrtd_pop_nonce,
+  mrtd,
+  ias,
+  context
+) => {
+  const {
+    appFetch = fetch,
+    walletInstanceAttestation,
+    wiaCryptoContext,
+  } = context;
+
+  const aud = issuerConf.openid_credential_issuer.credential_issuer;
+  const iss = WalletInstanceAttestation.decode(walletInstanceAttestation)
+    .payload.cnf.jwk.kid;
+
+  const signedWiaPoP = await createPopToken(
+    {
+      jti: `${uuidv4()}`,
+      aud,
+      iss,
+    },
+    wiaCryptoContext
+  );
+
+  const { kid } = await wiaCryptoContext.getPublicKey();
+
+  const mrtd_validation_jwt = await new SignJWT(wiaCryptoContext)
+    .setProtectedHeader({
+      typ: "mrtd-ias+jwt",
+      kid,
+    })
+    .setPayload({
+      iss,
+      aud,
+      document_type: "cie",
+      mrtd,
+      ias,
+    })
+    .setIssuedAt()
+    .setExpirationTime("5m")
+    .sign();
+
+  const requestBody = {
+    mrtd_validation_jwt,
+    mrtd_auth_session,
+    mrtd_pop_nonce,
+  };
+
+  const verifyResult = await appFetch(verifyUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "OAuth-Client-Attestation": walletInstanceAttestation,
+      "OAuth-Client-Attestation-PoP": signedWiaPoP,
+    },
+    body: JSON.stringify(requestBody),
+  })
+    .then(hasStatusOrThrow(202, IssuerResponseError))
+    .then((res) => res.json());
+
+  const verifyResultParsed = MrtdPopVerificationResult.parse(verifyResult);
+  return verifyResultParsed;
+};
+
+/**
+ * WARNING: This function must be called after {@link validateChallenge}. The generated authUrl must be used to open a browser or webview capable of catching the redirectSchema to perform a get request to the authorization endpoint.
+ * Builds the callback URL to which the end user should be redirected to continue the authentication flow after the MRTD challenge validation.
+ * @param redirectUri - The redirect URI provided by the issuer after the challenge validation to continue the authentication flow.
+ * @param valPopNonce - The MRTD validation PoP nonce obtained from the challenge validation response.
+ * @param authSession - The MRTD authentication session identifier used for session binding.
+ * @returns An object containing the callback URL
+ */
+export const buildChallengeCallbackUrl: BuildChallengeCallbackUrl = async (
+  redirectUri,
+  valPopNonce,
+  authSession
+) => {
+  const params = new URLSearchParams({
+    mrtd_val_pop_nonce: valPopNonce,
+    mrtd_auth_session: authSession,
+  });
+
+  const callbackUrl = `${redirectUri}?${params}`;
+  return { callbackUrl };
+};

package/src/credential/issuance/mrtd-pop/README.md

@@ -0,0 +1,92 @@
+# MRTD PoP flow
+
+**MRTD-PoP (Machine Readable Travel Document - Proof of Possession)** flow for the IO Wallet, following the [eID Wallet L2+ Credential Issuance specification](https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/credential-issuance-l2plus.html).
+
+The MRTD-PoP flow is used to prove possession of an MRTD (such as a CIE) during the issuance of high-assurance credentials. The process involves a challenge-response protocol between the wallet and the issuer, leveraging JWTs and cryptographic attestation.
+
+This flow is part of the [PID issuance flow](../README.md) and must be started after the `continueUserAuthorizationWithMRTDPoPChallenge` function. Once MRTD PoP is completed, the PID issuance flow must continue with the `completeUserAuthorizationWithQueryMode` function with the authorization url obtained from the validation.
+
+> **⚠️ Important**: The entire flow must be initiated and concluded within the same web context (e.g., the same WebView instance) to maintain session continuity. Using different contexts (such as switching between an external browser and a WebView) will result in session loss and authentication failures due to cookie/session mismatch (JSESSIONID).
+
+## Sequence Diagram
+
+```mermaid
+graph TD;
+    A@{ shape: subproc, label: "continueUserAuthorizationWithMRTDPoPChallenge" }
+    subgraph MRTD PoP
+    B[verifyAndParseChallengeInfo]
+    C[initChallenge]
+    E[validateChallenge]
+    end
+    F@{ shape: subproc, label: "completeUserAuthorizationWithQueryModeChallenge" }
+
+
+    A -.-> B
+    B --> C
+    C -->E
+    E -.-> F
+
+```
+
+## Example
+
+```typescript
+// Verify and parse challenge info and extract challenge data: initialization url, session and nonce
+const {
+  htu: initUrl,
+  mrtd_auth_session,
+  mrtd_pop_jwt_nonce,
+} = await Credential.Issuance.MRTDPoP.verifyAndParseChallengeInfo(
+  issuerConf,
+  challenge_info,
+  { wiaCryptoContext }
+);
+
+// Initialize challenge and obtain the challenge text to sign the CIE PACE protocol and validation url
+const {
+  htu: validationUrl,
+  challenge,
+  mrtd_pop_nonce,
+} = await Credential.Issuance.MRTDPoP.initChallenge(
+  issuerConf,
+  initUrl,
+  mrtd_auth_session,
+  mrtd_pop_jwt_nonce,
+  {
+    walletInstanceAttestation,
+    wiaCryptoContext,
+    appFetch,
+  }
+);
+
+// CIE cryptographic interaction: you need to sign the challenge with the CIE through NFC interaction
+const { nis, mrtds } = /* NFC interactions functions */
+
+// Validate challenge
+const { mrtd_val_pop_nonce, redirect_uri } =
+  await Credential.Issuance.MRTDPoP.validateChallenge(
+    issuerConf,
+    validationUrl,
+    mrtd_auth_session,
+    mrtd_pop_nonce,
+    mrtd,
+    ias,
+    {
+      walletInstanceAttestation,
+      wiaCryptoContext,
+      appFetch,
+    }
+  );
+
+// Build the callback url
+const { callbackUrl } = await Credential.Issuance.buildChallengeCallbackUrl(
+  redirect_uri,
+  mrtd_val_pop_nonce,
+  mrtd_auth_session
+);
+
+// The generated authUrl must be used to open a browser or webview capable of catching the redirectSchema to perform a get request to the authorization endpoint.
+const authRedirectUrl = /* From a browser or webview redirect */
+
+// Use the authRedirectUrl to continue the PID issuance flow
+```

package/src/credential/issuance/mrtd-pop/index.ts

@@ -0,0 +1,27 @@
+import {
+  verifyAndParseChallengeInfo,
+  type VerifyAndParseChallengeInfo,
+} from "./01-verify-and-parse-challenge-info";
+import { initChallenge, type InitChallenge } from "./02-init-challenge";
+import {
+  validateChallenge,
+  buildChallengeCallbackUrl,
+  type ValidateChallenge,
+  type BuildChallengeCallbackUrl,
+} from "./03-validate-challenge";
+import type { MrtdPayload, IasPayload } from "./types";
+
+export {
+  verifyAndParseChallengeInfo,
+  initChallenge,
+  validateChallenge,
+  buildChallengeCallbackUrl,
+};
+export type {
+  VerifyAndParseChallengeInfo,
+  InitChallenge,
+  ValidateChallenge,
+  BuildChallengeCallbackUrl,
+  MrtdPayload,
+  IasPayload,
+};

package/src/credential/issuance/mrtd-pop/types.ts

@@ -0,0 +1,65 @@
+import * as z from "zod";
+
+export type MrtdProofChallengeInfo = z.infer<typeof MrtdProofChallengeInfo>;
+export const MrtdProofChallengeInfo = z.object({
+  protectedHeader: z.object({
+    typ: z.literal("mrtd-ias+jwt"),
+    alg: z.string(),
+    kid: z.string(),
+  }),
+  payload: z.object({
+    iss: z.string(),
+    aud: z.string(),
+    iat: z.number(),
+    exp: z.number(),
+    status: z.literal("require_interaction"),
+    type: z.literal("mrtd+ias"),
+    mrtd_auth_session: z.string(),
+    state: z.string(),
+    mrtd_pop_jwt_nonce: z.string(),
+    htu: z.string(),
+    htm: z.literal("POST"),
+  }),
+});
+
+export type MrtdPoPChallenge = z.infer<typeof MrtdPoPChallenge>;
+export const MrtdPoPChallenge = z.object({
+  protectedHeader: z.object({
+    typ: z.literal("mrtd-ias-pop+jwt"),
+    alg: z.string(),
+    kid: z.string(),
+  }),
+  payload: z.object({
+    iss: z.string(),
+    aud: z.string(),
+    iat: z.number(),
+    exp: z.number(),
+    challenge: z.string(),
+    mrtd_pop_nonce: z.string(),
+    mrz: z.string().optional(),
+    htu: z.string(),
+    htm: z.literal("POST"),
+  }),
+});
+
+export type MrtdPayload = {
+  dg1: string;
+  dg11: string;
+  sod_mrtd: string;
+};
+
+export type IasPayload = {
+  ias_pk: string;
+  sod_ias: string;
+  challenge_signed: string;
+};
+
+export type MrtdPopVerificationResult = z.infer<
+  typeof MrtdPopVerificationResult
+>;
+export const MrtdPopVerificationResult = z.object({
+  status: z.literal("require_interaction"),
+  type: z.literal("redirect_to_web"),
+  mrtd_val_pop_nonce: z.string(),
+  redirect_uri: z.string(),
+});

package/src/utils/auth.ts

@@ -35,3 +35,15 @@ export const AuthorizationErrorShape = z.object({
  * Type of the identification result.
  */
 export type AuthorizationResult = z.infer<typeof AuthorizationResultShape>;
+
+/**
+ * MRTD PoP Challenge Info response structure
+ */
+
+export const AuthorizationChallengeResultShape = z.object({
+  challenge_info: z.string(),
+});
+
+export type AuthorizationChallengeResult = z.infer<
+  typeof AuthorizationChallengeResultShape
+>;

package/src/utils/par.ts

@@ -12,10 +12,18 @@ import { IssuerResponseError } from "./errors";
 import { LogLevel, Logger } from "./logging";
 
 export type AuthorizationDetail = z.infer<typeof AuthorizationDetail>;
-export const AuthorizationDetail = z.object({
-  type: z.literal("openid_credential"),
-  credential_configuration_id: z.string(),
-});
+export const AuthorizationDetail = z.union([
+  z.object({
+    type: z.literal("openid_credential"),
+    credential_configuration_id: z.string(),
+  }),
+  z.object({
+    type: z.literal("it_l2+document_proof"),
+    idphinting: z.string(),
+    challenge_method: z.literal("mrtd+ias"),
+    challenge_redirect_uri: z.string(),
+  }),
+]);
 
 export type AuthorizationDetails = z.infer<typeof AuthorizationDetails>;
 export const AuthorizationDetails = z.array(AuthorizationDetail);