@pagopa/io-react-native-wallet 2.5.1 → 3.0.0

package/src/credential/issuance/common/06-verify-and-parse-credential.sdjwt.ts

@@ -0,0 +1,261 @@
+import {
+  getJwkFromHeader,
+  type CryptoContext,
+  decode,
+} from "@pagopa/io-react-native-jwt";
+import { type SDJwt, SDJwtInstance } from "@sd-jwt/core";
+import { digest, ES256 } from "@sd-jwt/crypto-nodejs";
+import { isPathEqual, isPrefixOf } from "../../../utils/parser";
+import { IoWalletError } from "../../../utils/errors";
+import { LogLevel, Logger } from "../../../utils/logging";
+import { isSameThumbprint, type JWK } from "../../../utils/jwk";
+import type { SdJwt4VCBase } from "../../../sd-jwt/types";
+import type { IssuanceApi, IssuerConfig, ParsedCredential } from "../api";
+
+type CredentialConf =
+  IssuerConfig["credential_configurations_supported"][string];
+
+/**
+ * Parse a Sd-Jwt credential according to the issuer configuration
+ * @param credentialConfig - the list of supported credentials, as defined in the issuer configuration with their claims metadata
+ * @param parsedCredentialRaw - the raw parsed credential
+ * @param ignoreMissingAttributes - skip error when attributes declared in the issuer configuration are not found within disclosures
+ * @param includeUndefinedAttributes - include attributes not explicitly declared in the issuer configuration
+ * @returns The parsed credential with attributes in plain value
+ */
+const parseCredentialSdJwt = (
+  credentialConfig: CredentialConf,
+  parsedCredentialRaw: Record<string, unknown>,
+  ignoreMissingAttributes: boolean = false,
+  includeUndefinedAttributes: boolean = false
+): ParsedCredential => {
+  const claimsMetadata = credentialConfig.claims || [];
+
+  // Check that all mandatory attributes defined in the issuer configuration are present in the credential
+  if (!ignoreMissingAttributes) {
+    const missingPaths: string[] = [];
+    const rootKeysToVerify = new Set(
+      claimsMetadata
+        .map((c) => c.path[0])
+        .filter((p): p is string => typeof p === "string")
+    );
+
+    for (const rootKey of rootKeysToVerify) {
+      if (!(rootKey in parsedCredentialRaw)) {
+        missingPaths.push(rootKey);
+      }
+    }
+
+    if (missingPaths.length > 0) {
+      const missing = missingPaths.join(", ");
+      const received = Object.keys(parsedCredentialRaw).join(", ");
+      throw new IoWalletError(
+        `Some attributes are missing in the credential. Missing: [${missing}], received: [${received}]`
+      );
+    }
+  }
+
+  /**
+   * Helper to find display metadata for any given path
+   */
+  const getDisplayNames = (
+    path: (string | number | null)[]
+  ): Record<string, string> | undefined => {
+    const match = claimsMetadata.find((c) => isPathEqual(c.path, path));
+    if (!match) return undefined;
+
+    const nameMap: Record<string, string> = {};
+    for (const entry of match.display) {
+      nameMap[entry.locale] = entry.name;
+    }
+    return nameMap;
+  };
+
+  /**
+   * Recursive function to build the localized structure
+   */
+  const processLevel = (
+    currentData: unknown,
+    currentPath: (string | number | null)[]
+  ): unknown => {
+    // Handle Arrays
+    if (Array.isArray(currentData)) {
+      return currentData.map((item) =>
+        processLevel(item, [...currentPath, null])
+      );
+    }
+
+    // Handle Objects
+    if (typeof currentData !== "object" || currentData === null) {
+      return currentData;
+    }
+
+    const dataObj = currentData as Record<string, unknown>;
+    const result: ParsedCredential = {};
+    const processedKeys = new Set<string | number>();
+
+    // Identify unique keys in config at this level
+    const configKeysAtThisLevel: (string | number)[] = [];
+    for (const claim of claimsMetadata) {
+      // Check if the claim path starts with the current path
+      if (isPrefixOf(currentPath, claim.path)) {
+        const nextPart = claim.path[currentPath.length];
+        if (
+          (typeof nextPart === "string" || typeof nextPart === "number") &&
+          !configKeysAtThisLevel.includes(nextPart)
+        ) {
+          configKeysAtThisLevel.push(nextPart);
+        }
+      }
+    }
+
+    // Process keys
+    for (const key of configKeysAtThisLevel) {
+      const stringKey = key.toString();
+      const dataValue = dataObj[stringKey];
+      if (dataValue === undefined) continue;
+
+      const newPath = [...currentPath, key];
+
+      let localizedNames = getDisplayNames(newPath);
+
+      // Fallback for arrays
+      if (!localizedNames && Array.isArray(dataValue)) {
+        localizedNames = getDisplayNames([...newPath, null]);
+      }
+
+      result[stringKey] = {
+        name: localizedNames || stringKey,
+        value: processLevel(dataValue, newPath),
+      };
+
+      processedKeys.add(key);
+    }
+
+    // Handle Undefined Attributes
+    if (includeUndefinedAttributes) {
+      for (const [key, value] of Object.entries(dataObj)) {
+        if (!processedKeys.has(key)) {
+          result[key] = {
+            name: key,
+            value: value,
+          };
+        }
+      }
+    }
+
+    return result;
+  };
+
+  return processLevel(parsedCredentialRaw, []) as ParsedCredential;
+};
+
+/**
+ * Given a credential, verify it's in the supported format
+ * and the credential is correctly signed
+ * and it's bound to the given key
+ *
+ * @param rawCredential The received credential
+ * @param issuerKeys The set of public keys of the issuer,
+ * which will be used to verify the signature
+ * @param holderBindingContext The access to the holder's key
+ *
+ * @throws If the signature verification fails
+ * @throws If the credential is not in the SdJwt4VC format
+ * @throws If the holder binding is not properly configured
+ *
+ */
+async function verifyCredentialSdJwt(
+  rawCredential: string,
+  issuerKeys: JWK[],
+  holderBindingContext: CryptoContext
+): Promise<SDJwt> {
+  const { protectedHeader } = decode(rawCredential);
+  const verifierJwk = getJwkFromHeader(protectedHeader, issuerKeys);
+
+  const sdJwtInstance = new SDJwtInstance({
+    hasher: digest,
+    verifier: await ES256.getVerifier(verifierJwk),
+  });
+
+  const [verifiedCredential, holderBindingKey] = await Promise.all([
+    sdJwtInstance.verify(rawCredential),
+    holderBindingContext.getPublicKey(),
+  ]);
+
+  const { cnf } = verifiedCredential.payload as SdJwt4VCBase["payload"];
+  if (!(await isSameThumbprint(cnf.jwk, holderBindingKey as JWK))) {
+    const message = `Failed to verify holder binding, expected kid: ${holderBindingKey.kid}, got: ${cnf.jwk.kid}`;
+    Logger.log(LogLevel.ERROR, message);
+    throw new IoWalletError(message);
+  }
+
+  return await sdJwtInstance.decode(rawCredential);
+}
+
+export const verifyAndParseCredentialSdJwt: IssuanceApi["verifyAndParseCredential"] =
+  async (
+    issuerConf,
+    credential,
+    credentialConfigurationId,
+    {
+      credentialCryptoContext,
+      ignoreMissingAttributes,
+      includeUndefinedAttributes,
+    }
+  ) => {
+    const decoded = await verifyCredentialSdJwt(
+      credential,
+      issuerConf.keys,
+      credentialCryptoContext
+    );
+
+    Logger.log(
+      LogLevel.DEBUG,
+      `Decoded credential: ${JSON.stringify(decoded)}`
+    );
+
+    const credentialConfig =
+      issuerConf.credential_configurations_supported[credentialConfigurationId];
+
+    if (!credentialConfig) {
+      Logger.log(
+        LogLevel.ERROR,
+        `Credential type not supported by the issuer: ${credentialConfigurationId}`
+      );
+      throw new IoWalletError("Credential type not supported by the issuer");
+    }
+
+    const parsedCredentialRaw = (await decoded.getClaims(digest)) as Record<
+      string,
+      unknown
+    >;
+
+    const parsedCredential = parseCredentialSdJwt(
+      credentialConfig,
+      parsedCredentialRaw,
+      ignoreMissingAttributes,
+      includeUndefinedAttributes
+    );
+
+    const issuedAt =
+      typeof parsedCredentialRaw.iat === "number"
+        ? new Date(parsedCredentialRaw.iat * 1000)
+        : undefined;
+
+    if (typeof parsedCredentialRaw.exp !== "number") {
+      throw new IoWalletError("Invalid or missing expiration claim (exp)");
+    }
+    const expiration = new Date(parsedCredentialRaw.exp * 1000);
+
+    Logger.log(
+      LogLevel.DEBUG,
+      `Parsed credential: ${JSON.stringify(parsedCredential)}\nIssued at: ${issuedAt}`
+    );
+
+    return {
+      parsedCredential,
+      expiration,
+      issuedAt,
+    };
+  };

package/src/credential/issuance/common/authorization.ts

@@ -0,0 +1,89 @@
+import { IoWalletError } from "../../../utils/errors";
+import { LogLevel, Logger } from "../../../utils/logging";
+import { AuthorizationDetail } from "../../../utils/par";
+import type { IssuerConfig } from "../api";
+
+type ResponseMode = "query" | "form_post.jwt";
+
+/**
+ * Ensures that the credential type requested is supported by the issuer and contained in the
+ * issuer configuration.
+ * @param issuerConf The issuer configuration returned by {@link evaluateIssuerTrust}
+ * @param credentialId The credential configuration ID to be requested;
+ * @returns The credential definition to be used in the request which includes the format and the type and its type
+ */
+export const selectCredentialDefinition = (
+  issuerConf: IssuerConfig,
+  credentialId: string
+): AuthorizationDetail => {
+  const credential_configurations_supported =
+    issuerConf.credential_configurations_supported;
+
+  const [result] = Object.keys(credential_configurations_supported)
+    .filter((e) => e.includes(credentialId))
+    .map(() => ({
+      credential_configuration_id: credentialId,
+      type: "openid_credential" as const,
+    }));
+
+  if (!result) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Requested credential ${credentialId} is not supported by the issuer according to its configuration ${JSON.stringify(credential_configurations_supported)}`
+    );
+    throw new IoWalletError(`No credential support the type '${credentialId}'`);
+  }
+  return result;
+};
+
+/**
+ * Ensures that the response mode requested is supported by the issuer and contained in the issuer configuration.
+ * When multiple credentials are provided, all of them must support the same response_mode.
+ * @param issuerConf The issuer configuration
+ * @param credentialIds The credential configuration IDs to be requested
+ * @returns The response mode to be used in the request, "query" for PersonIdentificationData and "form_post.jwt" for all other types.
+ */
+export const selectResponseMode = (
+  issuerConf: IssuerConfig,
+  credentialIds: string[]
+): ResponseMode => {
+  const responseModeSet = new Set<ResponseMode>();
+
+  for (const credentialId of credentialIds) {
+    responseModeSet.add(
+      credentialId.match(/PersonIdentificationData/i)
+        ? "query"
+        : "form_post.jwt"
+    );
+  }
+
+  if (responseModeSet.size !== 1) {
+    Logger.log(
+      LogLevel.ERROR,
+      `${credentialIds} have incompatible response_mode: ${[...responseModeSet.values()]}`
+    );
+    throw new IoWalletError(
+      "Requested credentials have incompatible response_mode and cannot be requested with the same PAR request"
+    );
+  }
+
+  const [responseMode] = responseModeSet.values();
+
+  Logger.log(
+    LogLevel.DEBUG,
+    `Selected response mode ${responseMode} for credential IDs ${credentialIds}`
+  );
+
+  const responseModeSupported = issuerConf.response_modes_supported;
+  if (responseModeSupported && !responseModeSupported.includes(responseMode!)) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Requested response mode ${responseMode} is not supported by the issuer according to its configuration ${JSON.stringify(responseModeSupported)}`
+    );
+    throw new IoWalletError(
+      `No response mode support for IDs '${credentialIds}'`
+    );
+  }
+
+  return responseMode!;
+};

package/src/credential/issuance/common/errors.ts

@@ -0,0 +1,29 @@
+import { IoWalletError, serializeAttrs } from "../../../utils/errors";
+
+/**
+ * An error subclass thrown when an error occurs during the authorization process.
+ */
+export class AuthorizationError extends IoWalletError {
+  code = "ERR_IO_WALLET_AUTHORIZATION_ERROR";
+
+  constructor(message?: string) {
+    super(message);
+  }
+}
+
+/**
+ * An error subclass thrown when an error occurs during the authorization process with the IDP.
+ * It contains the error and error description returned by the IDP.
+ */
+export class AuthorizationIdpError extends IoWalletError {
+  code = "ERR_IO_WALLET_IDENTIFICATION_RESPONSE_PARSING_FAILED";
+
+  error: string;
+  errorDescription?: string;
+
+  constructor(error: string, errorDescription?: string) {
+    super(serializeAttrs({ error, errorDescription }));
+    this.error = error;
+    this.errorDescription = errorDescription;
+  }
+}

package/src/credential/issuance/index.ts

@@ -1,62 +1,5 @@
-import { type StartFlow } from "./01-start-flow";
-import {
-  evaluateIssuerTrust,
-  type EvaluateIssuerTrust,
-} from "./02-evaluate-issuer-trust";
-import {
-  startUserAuthorization,
-  type StartUserAuthorization,
-} from "./03-start-user-authorization";
-import {
-  continueUserAuthorizationWithMRTDPoPChallenge,
-  completeUserAuthorizationWithQueryMode,
-  completeUserAuthorizationWithFormPostJwtMode,
-  parseAuthorizationResponse,
-  buildAuthorizationUrl,
-  getRequestedCredentialToBePresented,
-  type ContinueUserAuthorizationWithMRTDPoPChallenge,
-  type CompleteUserAuthorizationWithQueryMode,
-  type CompleteUserAuthorizationWithFormPostJwtMode,
-  type GetRequestedCredentialToBePresented,
-  type BuildAuthorizationUrl,
-} from "./04-complete-user-authorization";
-import { authorizeAccess, type AuthorizeAccess } from "./05-authorize-access";
-import {
-  obtainCredential,
-  type ObtainCredential,
-} from "./06-obtain-credential";
-import {
-  verifyAndParseCredential,
-  type VerifyAndParseCredential,
-} from "./07-verify-and-parse-credential";
-import * as Errors from "./errors";
-import * as MRTDPoP from "./mrtd-pop";
-
-export {
-  MRTDPoP,
-  evaluateIssuerTrust,
-  startUserAuthorization,
-  buildAuthorizationUrl,
-  completeUserAuthorizationWithQueryMode,
-  continueUserAuthorizationWithMRTDPoPChallenge,
-  getRequestedCredentialToBePresented,
-  completeUserAuthorizationWithFormPostJwtMode,
-  authorizeAccess,
-  obtainCredential,
-  verifyAndParseCredential,
-  parseAuthorizationResponse,
-  Errors,
-};
-export type {
-  StartFlow,
-  EvaluateIssuerTrust,
-  StartUserAuthorization,
-  BuildAuthorizationUrl,
-  ContinueUserAuthorizationWithMRTDPoPChallenge,
-  CompleteUserAuthorizationWithQueryMode,
-  GetRequestedCredentialToBePresented,
-  CompleteUserAuthorizationWithFormPostJwtMode,
-  AuthorizeAccess,
-  ObtainCredential,
-  VerifyAndParseCredential,
-};
+import * as Errors from "./common/errors";
+export { Errors };
+export type * from "./api";
+export { Issuance as V1_0_0 } from "./v1.0.0";
+export { Issuance as V1_3_3 } from "./v1.3.3";

package/src/credential/issuance/mrtd-pop/01-verify-and-parse-challenge-info.ts

@@ -1,70 +1,25 @@
-import {
-  decode as decodeJwt,
-  verify as verifyJwt,
-  type CryptoContext,
-} from "@pagopa/io-react-native-jwt";
-import { MrtdProofChallengeInfo } from "./types";
-import type { EvaluateIssuerTrust } from "../../issuance";
-import type { Out } from "../../../utils/misc";
+import { verifyMrtdChallenge } from "@pagopa/io-wallet-oauth2";
 import { IoWalletError } from "../../../utils/errors";
+import { createVerifyJwtFromJwks } from "../../../utils/callbacks";
+import type { MRTDPoPApi } from "../api/mrtd-pop";
 
-export type VerifyAndParseChallengeInfo = (
-  issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
-  challengeInfoJwt: string,
-  context: {
-    wiaCryptoContext: CryptoContext;
-  }
-) => Promise<MrtdProofChallengeInfo["payload"]>;
+export const verifyAndParseChallengeInfo: MRTDPoPApi["verifyAndParseChallengeInfo"] =
+  async (issuerConf, challengeInfoJwt, { wiaCryptoContext }) => {
+    const clientId = await wiaCryptoContext.getPublicKey().then((x) => x.kid);
 
-/**
- * Verifies and parses the payload of a MRTD Proof Challenge Info JWT obtained after the primary authentication.
- *
- * This function performs the following steps:
- * 1. Validates the JWT signature using the issuer's JWKS.
- * 2. Decodes the JWT and parses its structure according to the {@link MrtdProofChallengeInfo} schema.
- * 3. Verifies that the `aud` claim matches the client's public key ID.
- * 4. Checks that the JWT is not expired and was not issued in the future.
- *
- * @param issuerConf - The issuer configuration containing the JWKS for signature verification.
- * @param challengeInfoJwt - The JWT string representing the MRTD Proof Challenge Info.
- * @param context - The context containing the WIA crypto context used to retrieve the client public key.
- * @returns The parsed payload of the MRTD Proof Challenge Info JWT.
- * @throws {Error} If the JWT signature is invalid, the structure is malformed, the `aud` claim does not match,
- * or the JWT is expired/not yet valid.
- */
-export const verifyAndParseChallengeInfo: VerifyAndParseChallengeInfo = async (
-  issuerConf,
-  challengeInfoJwt: string,
-  { wiaCryptoContext }
-) => {
-  // Verify JWT signature
-  await verifyJwt(
-    challengeInfoJwt,
-    issuerConf.oauth_authorization_server.jwks.keys
-  );
+    if (!clientId) {
+      throw new IoWalletError(
+        "Could not extract client_id from Wallet Attestation"
+      );
+    }
 
-  // Decode JWT
-  const challengeInfoDecoded = decodeJwt(challengeInfoJwt);
+    const verified = await verifyMrtdChallenge({
+      challengeJwt: challengeInfoJwt,
+      clientId,
+      callbacks: {
+        verifyJwt: createVerifyJwtFromJwks(issuerConf.keys),
+      },
+    });
 
-  // Parse and validate structure
-  const challengeInfoParsed =
-    MrtdProofChallengeInfo.safeParse(challengeInfoDecoded);
-  if (!challengeInfoParsed.success) {
-    throw new IoWalletError("Malformed challenge info.");
-  }
-  const payload = challengeInfoParsed.data.payload;
-
-  // Verify aud claim
-  const clientId = await wiaCryptoContext.getPublicKey().then((_) => _.kid);
-  if (payload.aud !== clientId) {
-    throw new IoWalletError("aud claim does not match client_id.");
-  }
-
-  // Verify iat and exp
-  const now = Math.floor(Date.now() / 1000);
-  if (payload.iat > now || payload.exp < now) {
-    throw new IoWalletError("JWT is not valid (issued in future or expired).");
-  }
-
-  return payload;
-};
+    return verified.payload;
+  };

package/src/credential/issuance/mrtd-pop/02-init-challenge.ts

@@ -1,44 +1,18 @@
-import { hasStatusOrThrow, type Out } from "../../../utils/misc";
-import type { CryptoContext } from "@pagopa/io-react-native-jwt";
 import { v4 as uuidv4 } from "uuid";
+import { fetchMrtdPopInit } from "@pagopa/io-wallet-oauth2";
+import { UnexpectedStatusCodeError as SdkUnexpectedStatusCodeError } from "@pagopa/io-wallet-utils";
 import { createPopToken } from "../../../utils/pop";
 import { Logger, LogLevel } from "../../../utils/logging";
-import * as WalletInstanceAttestation from "../../../wallet-instance-attestation";
-import type { EvaluateIssuerTrust } from "../../issuance";
+import * as WalletInstanceAttestation from "../../../wallet-instance-attestation/v1.0.0/utils"; // TODO: decouple from version 1.0.0
 import {
   IssuerResponseError,
   IssuerResponseErrorCodes,
   ResponseErrorBuilder,
-  UnexpectedStatusCodeError,
 } from "../../../utils/errors";
-import { decode as decodeJwt } from "@pagopa/io-react-native-jwt";
-import { MrtdPoPChallenge } from "./types";
+import type { MRTDPoPApi } from "../api/mrtd-pop";
+import { createVerifyJwtFromJwks } from "../../../utils/callbacks";
 
-export type InitChallenge = (
-  issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
-  initUrl: string,
-  mrtd_auth_session: string,
-  mrtd_pop_jwt_nonce: string,
-  context: {
-    wiaCryptoContext: CryptoContext;
-    walletInstanceAttestation: string;
-    appFetch?: GlobalFetch["fetch"];
-  }
-) => Promise<MrtdPoPChallenge["payload"]>;
-
-/**
- * Initialaizes the MRTD challenge with the data received from the issuer after the primary authentication.
- * This function must be called after {@link verifyAndParseChallengeInfo}.
- *
- * @param issuerConf - The issuer configuration containing the JWKS for signature verification.
- * @param initUrl - The endpoint to call to initialize the challenge.
- * @param mrtd_auth_session - Session identifier for session binding obtained from the MRTD Proof JWT.
- * @param mrtd_pop_jwt_nonce - Nonce value obtained from the MRTD Proof JWT.
- * @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 payload of the MRTD PoP Challenge JWT.
- */
-export const initChallenge: InitChallenge = async (
+export const initChallenge: MRTDPoPApi["initChallenge"] = async (
   issuerConf,
   initUrl,
   mrtd_auth_session,
@@ -51,47 +25,42 @@ export const initChallenge: InitChallenge = async (
     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,
+      jti: uuidv4(),
+      aud: issuerConf.credential_issuer,
       iss,
     },
     wiaCryptoContext
   );
 
-  const requestBody = {
-    mrtd_auth_session,
-    mrtd_pop_jwt_nonce,
-  };
-
-  const mrtdPoPChallengeJwt = await appFetch(initUrl, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "OAuth-Client-Attestation": walletInstanceAttestation,
-      "OAuth-Client-Attestation-PoP": signedWiaPoP,
+  const initResult = await fetchMrtdPopInit({
+    popInitEndpoint: initUrl,
+    mrtdAuthSession: mrtd_auth_session,
+    mrtdPopJwtNonce: mrtd_pop_jwt_nonce,
+    walletAttestation: walletInstanceAttestation,
+    clientAttestationDPoP: signedWiaPoP,
+    callbacks: {
+      verifyJwt: createVerifyJwtFromJwks(issuerConf.keys),
+      fetch: appFetch,
     },
-    body: JSON.stringify(requestBody),
-  })
-    .then(hasStatusOrThrow(202))
-    .then((res) => res.text())
-    .catch(handleInitChallengeError);
-
-  const mrtdPoPChallengeDecoded = decodeJwt(mrtdPoPChallengeJwt);
-  const { payload } = MrtdPoPChallenge.parse(mrtdPoPChallengeDecoded);
+  }).catch(handleInitChallengeError);
 
-  return payload;
+  return {
+    challenge: initResult.challenge,
+    mrtd_pop_nonce: initResult.mrtdPopNonce,
+    pop_verify_endpoint: initResult.popVerifyEndpoint,
+    mrz: initResult.mrz,
+  };
 };
 
 const handleInitChallengeError = (e: unknown) => {
   Logger.log(LogLevel.ERROR, `Failed to get MRTD challenge: ${e}`);
 
-  if (!(e instanceof UnexpectedStatusCodeError)) {
+  if (!(e instanceof SdkUnexpectedStatusCodeError)) {
     throw e;
   }