@pagopa/io-react-native-wallet 0.28.2 → 0.30.0

package/src/credential/issuance/06-obtain-credential.ts

@@ -17,6 +17,7 @@ import {
 import { CredentialResponse } from "./types";
 import { createDPopToken } from "../../utils/dpop";
 import { v4 as uuidv4 } from "uuid";
+import { LogLevel, Logger } from "../../utils/logging";
 
 export type ObtainCredential = (
   issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
@@ -27,7 +28,8 @@ export type ObtainCredential = (
     dPopCryptoContext: CryptoContext;
     credentialCryptoContext: CryptoContext;
     appFetch?: GlobalFetch["fetch"];
-  }
+  },
+  operationType?: "reissuing"
 ) => Promise<CredentialResponse>;
 
 export const createNonceProof = async (
@@ -73,7 +75,8 @@ export const obtainCredential: ObtainCredential = async (
   accessToken,
   clientId,
   credentialDefinition,
-  context
+  context,
+  operationType
 ) => {
   const {
     credentialCryptoContext,
@@ -95,6 +98,8 @@ export const obtainCredential: ObtainCredential = async (
     credentialCryptoContext
   );
 
+  Logger.log(LogLevel.DEBUG, `Signed nonce proof: ${signedNonceProof}`);
+
   // Validation of accessTokenResponse.authorization_details if contain credentialDefinition
   const containsCredentialDefinition = accessToken.authorization_details.some(
     (c) =>
@@ -105,6 +110,10 @@ export const obtainCredential: ObtainCredential = async (
   );
 
   if (!containsCredentialDefinition) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Credential definition not found in the access token response ${accessToken.authorization_details}`
+    );
     throw new ValidationFailed({
       message:
         "The access token response does not contain the requested credential",
@@ -123,6 +132,11 @@ export const obtainCredential: ObtainCredential = async (
     },
   };
 
+  Logger.log(
+    LogLevel.DEBUG,
+    `Credential request body: ${JSON.stringify(credentialRequestFormBody)}`
+  );
+
   const tokenRequestSignedDPop = await createDPopToken(
     {
       htm: "POST",
@@ -132,12 +146,16 @@ export const obtainCredential: ObtainCredential = async (
     },
     dPopCryptoContext
   );
+
+  Logger.log(LogLevel.DEBUG, `Token request DPoP: ${tokenRequestSignedDPop}`);
+
   const credentialRes = await appFetch(credentialUrl, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       DPoP: tokenRequestSignedDPop,
       Authorization: `${accessToken.token_type} ${accessToken.access_token}`,
+      ...(operationType === "reissuing" && { operationType }),
     },
     body: JSON.stringify(credentialRequestFormBody),
   })
@@ -147,12 +165,21 @@ export const obtainCredential: ObtainCredential = async (
     .catch(handleObtainCredentialError);
 
   if (!credentialRes.success) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Credential Response validation failed: ${credentialRes.error.message}`
+    );
     throw new ValidationFailed({
       message: "Credential Response validation failed",
       reason: credentialRes.error.message,
     });
   }
 
+  Logger.log(
+    LogLevel.DEBUG,
+    `Credential Response: ${JSON.stringify(credentialRes.data)}`
+  );
+
   return credentialRes.data;
 };
 
@@ -163,6 +190,8 @@ export const obtainCredential: ObtainCredential = async (
  * @throws {IssuerResponseError} with a specific code for more context
  */
 const handleObtainCredentialError = (e: unknown) => {
+  Logger.log(LogLevel.ERROR, `Error occurred while obtaining credential: ${e}`);
+
   if (!(e instanceof UnexpectedStatusCodeError)) {
     throw e;
   }

package/src/credential/issuance/07-verify-and-parse-credential.ts

@@ -7,6 +7,7 @@ import { verify as verifySdJwt } from "../../sd-jwt";
 import { getValueFromDisclosures } from "../../sd-jwt/converters";
 import type { JWK } from "../../utils/jwk";
 import type { ObtainCredential } from "./06-obtain-credential";
+import { LogLevel, Logger } from "../../utils/logging";
 
 export type VerifyAndParseCredential = (
   issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
@@ -62,10 +63,18 @@ const parseCredentialSdJwt = (
   const credentialSubject = credentials_supported[sdJwt.payload.vct];
 
   if (!credentialSubject) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Credential type not supported by the issuer: ${sdJwt.payload.vct}`
+    );
     throw new IoWalletError("Credential type not supported by the issuer");
   }
 
   if (credentialSubject.format !== sdJwt.header.typ) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Received credential is of an unknwown type. Expected one of [${credentialSubject.format}], received '${sdJwt.header.typ}'`
+    );
     throw new IoWalletError(
       `Received credential is of an unknwown type. Expected one of [${credentialSubject.format}], received '${sdJwt.header.typ}', `
     );
@@ -73,6 +82,7 @@ const parseCredentialSdJwt = (
 
   // transfrom a record { key: value } in an iterable of pairs [key, value]
   if (!credentialSubject.claims) {
+    Logger.log(LogLevel.ERROR, "Missing claims in the credential subject");
     throw new IoWalletError("Missing claims in the credential subject"); // TODO [SIW-1268]: should not be optional
   }
   const attrDefinitions = Object.entries(credentialSubject.claims);
@@ -85,6 +95,10 @@ const parseCredentialSdJwt = (
     const missing = attrsNotInDisclosures.map((_) => _[0 /* key */]).join(", ");
     const received = disclosures.map((_) => _[1 /* name */]).join(", ");
     if (!ignoreMissingAttributes) {
+      Logger.log(
+        LogLevel.ERROR,
+        `Some attributes are missing in the credential. Missing: [${missing}], received: [${received}]`
+      );
       throw new IoWalletError(
         `Some attributes are missing in the credential. Missing: [${missing}], received: [${received}]`
       );
@@ -172,6 +186,10 @@ async function verifyCredentialSdJwt(
   const { cnf } = decodedCredential.sdJwt.payload;
 
   if (!cnf.jwk.kid || cnf.jwk.kid !== holderBindingKey.kid) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Failed to verify holder binding, expected kid: ${holderBindingKey.kid}, got: ${decodedCredential.sdJwt.payload.cnf.jwk.kid}`
+    );
     throw new IoWalletError(
       `Failed to verify holder binding, expected kid: ${holderBindingKey.kid}, got: ${decodedCredential.sdJwt.payload.cnf.jwk.kid}`
     );
@@ -204,15 +222,21 @@ const verifyAndParseCredentialSdJwt: WithFormat<"vc+sd-jwt"> = async (
     credentialCryptoContext
   );
 
+  Logger.log(LogLevel.DEBUG, `Decoded credential: ${JSON.stringify(decoded)}`);
+
   const parsedCredential = parseCredentialSdJwt(
     issuerConf.openid_credential_issuer.credential_configurations_supported,
     decoded,
     ignoreMissingAttributes,
     includeUndefinedAttributes
   );
-
   const maybeIssuedAt = getValueFromDisclosures(decoded.disclosures, "iat");
 
+  Logger.log(
+    LogLevel.DEBUG,
+    `Parsed credential: ${JSON.stringify(parsedCredential)}\nIssued at: ${maybeIssuedAt}`
+  );
+
   return {
     parsedCredential,
     expiration: new Date(decoded.sdJwt.payload.exp * 1000),
@@ -243,6 +267,7 @@ export const verifyAndParseCredential: VerifyAndParseCredential = async (
   context
 ) => {
   if (format === "vc+sd-jwt") {
+    Logger.log(LogLevel.DEBUG, "Parsing credential in vc+sd-jwt format");
     return verifyAndParseCredentialSdJwt(
       issuerConf,
       credential,
@@ -251,5 +276,6 @@ export const verifyAndParseCredential: VerifyAndParseCredential = async (
     );
   }
 
+  Logger.log(LogLevel.ERROR, `Unsupported credential format: ${format}`);
   throw new IoWalletError(`Unsupported credential format: ${format}`);
 };

package/src/credential/presentation/01-start-flow.ts

@@ -2,9 +2,9 @@ import * as z from "zod";
 import { InvalidQRCodeError } from "./errors";
 
 const PresentationParams = z.object({
-  clientId: z.string().nonempty(),
-  requestUri: z.string().url(),
-  requestUriMethod: z.enum(["get", "post"]),
+  client_id: z.string().nonempty(),
+  request_uri: z.string().url(),
+  request_uri_method: z.enum(["get", "post"]),
   state: z.string().optional(),
 });
 export type PresentationParams = z.infer<typeof PresentationParams>;
@@ -13,24 +13,25 @@ export type PresentationParams = z.infer<typeof PresentationParams>;
  * The beginning of the presentation flow.
  * To be implemented accordind to the user touchpoint
  *
- * @param params Presentation parameters, depending on the starting touchoint
+ * @param params Presentation parameters, depending on the starting touchpoint
  * @returns The url for the Relying Party to connect with
  */
-export type StartFlow = (
-  params: Partial<PresentationParams>
-) => PresentationParams;
+export type StartFlow = (params: {
+  [K in keyof PresentationParams]?: PresentationParams[K] | null;
+}) => PresentationParams;
 
 /**
- * Start a presentation flow by decoding an incoming QR-code
+ * Start a presentation flow by validating the required parameters.
+ * Parameters are extracted from a url encoded in a QR code or in a deep link.
  *
- * @param params The encoded QR-code content
+ * @param params The parameters to be validated
  * @returns The url for the Relying Party to connect with
- * @throws If the provided qr code fails to be decoded
+ * @throws If the provided parameters are not valid
  */
 export const startFlowFromQR: StartFlow = (params) => {
   const result = PresentationParams.safeParse({
     ...params,
-    requestUriMethod: params.requestUriMethod ?? "get",
+    request_uri_method: params.request_uri_method ?? "get",
   });
 
   if (result.success) {

package/src/credential/presentation/03-get-request-object.ts

@@ -1,9 +1,9 @@
-import { hasStatusOrThrow, type Out } from "../../utils/misc";
-import type { StartFlow } from "./01-start-flow";
+import { RelyingPartyResponseError } from "../../utils/errors";
+import { hasStatusOrThrow } from "../../utils/misc";
 import { RequestObjectWalletCapabilities } from "./types";
 
 export type GetRequestObject = (
-  requestUri: Out<StartFlow>["requestUri"],
+  requestUri: string,
   context?: {
     appFetch?: GlobalFetch["fetch"];
     walletCapabilities?: RequestObjectWalletCapabilities;
@@ -41,7 +41,7 @@ export const getRequestObject: GetRequestObject = async (
       },
       body: formUrlEncodedBody.toString(),
     })
-      .then(hasStatusOrThrow(200))
+      .then(hasStatusOrThrow(200, RelyingPartyResponseError))
       .then((res) => res.text());
 
     return {
@@ -52,7 +52,7 @@ export const getRequestObject: GetRequestObject = async (
   const requestObjectEncodedJwt = await appFetch(requestUri, {
     method: "GET",
   })
-    .then(hasStatusOrThrow(200))
+    .then(hasStatusOrThrow(200, RelyingPartyResponseError))
     .then((res) => res.text());
 
   return {

package/src/credential/presentation/05-verify-request-object.ts

@@ -1,6 +1,6 @@
 import { decode as decodeJwt, verify } from "@pagopa/io-react-native-jwt";
 import type { RelyingPartyEntityConfiguration } from "../../trust";
-import { UnverifiedEntityError } from "./errors";
+import { InvalidRequestObjectError } from "./errors";
 import { RequestObject } from "./types";
 import { getJwksFromConfig } from "./04-retrieve-rp-jwks";
 
@@ -15,39 +15,38 @@ export type VerifyRequestObject = (
 ) => Promise<{ requestObject: RequestObject }>;
 
 /**
- * Function to verify the Request Object's signature and the client ID.
+ * Function to verify the Request Object's validity, from the signature to the required properties.
  * @param requestObjectEncodedJwt The Request Object in JWT format
  * @param context.clientId The client ID to verify
  * @param context.rpConf The Entity Configuration of the Relying Party
  * @param context.state Optional state
  * @returns The verified Request Object
+ * @throws {InvalidRequestObjectError} if the Request Object cannot be validated
  */
 export const verifyRequestObject: VerifyRequestObject = async (
   requestObjectEncodedJwt,
   { clientId, rpConf, rpSubject, state }
 ) => {
   const requestObjectJwt = decodeJwt(requestObjectEncodedJwt);
-  const { keys } = getJwksFromConfig(rpConf);
 
-  // Verify token signature to ensure the request object is authentic
-  const pubKey = keys?.find(
-    ({ kid }) => kid === requestObjectJwt.protectedHeader.kid
-  );
+  const pubKey = getSigPublicKey(rpConf, requestObjectJwt.protectedHeader.kid);
 
-  if (!pubKey) {
-    throw new UnverifiedEntityError("Request Object signature verification!");
+  try {
+    // Standard claims are verified within `verify`
+    await verify(requestObjectEncodedJwt, pubKey, { issuer: clientId });
+  } catch (_) {
+    throw new InvalidRequestObjectError(
+      "The Request Object signature verification failed"
+    );
   }
 
-  // Standard claims are verified within `verify`
-  await verify(requestObjectEncodedJwt, pubKey, { issuer: clientId });
-
-  const requestObject = RequestObject.parse(requestObjectJwt.payload);
+  const requestObject = validateRequestObjectShape(requestObjectJwt.payload);
 
   const isClientIdMatch =
     clientId === requestObject.client_id && clientId === rpSubject;
 
   if (!isClientIdMatch) {
-    throw new UnverifiedEntityError(
+    throw new InvalidRequestObjectError(
       "Client ID does not match Request Object or Entity Configuration"
     );
   }
@@ -56,8 +55,67 @@ export const verifyRequestObject: VerifyRequestObject = async (
     state && requestObject.state ? state === requestObject.state : true;
 
   if (!isStateMatch) {
-    throw new UnverifiedEntityError("State does not match Request Object");
+    throw new InvalidRequestObjectError(
+      "The provided state does not match the Request Object's"
+    );
   }
 
   return { requestObject };
 };
+
+/**
+ * Validate the shape of the Request Object to ensure all required properties are present and are of the expected type.
+ *
+ * @param payload The Request Object to validate
+ * @returns A valid Request Object
+ * @throws {InvalidRequestObjectError} when the Request Object cannot be parsed
+ */
+const validateRequestObjectShape = (payload: unknown): RequestObject => {
+  const requestObjectParse = RequestObject.safeParse(payload);
+
+  if (requestObjectParse.success) {
+    return requestObjectParse.data;
+  }
+
+  throw new InvalidRequestObjectError(
+    "The Request Object cannot be parsed successfully",
+    formatFlattenedZodErrors(requestObjectParse.error.flatten())
+  );
+};
+
+/**
+ * Get the public key to verify the Request Object's signature from the Relying Party's EC.
+ *
+ * @param rpConf The Relying Party's EC
+ * @param kid The identifier of the key to find
+ * @returns The corresponding public key to verify the signature
+ * @throws {InvalidRequestObjectError} when the key cannot be found
+ */
+const getSigPublicKey = (
+  rpConf: RelyingPartyEntityConfiguration["payload"]["metadata"],
+  kid: string | undefined
+) => {
+  try {
+    const { keys } = getJwksFromConfig(rpConf);
+
+    const pubKey = keys.find((k) => k.kid === kid);
+
+    if (!pubKey) throw new Error();
+
+    return pubKey;
+  } catch (_) {
+    throw new InvalidRequestObjectError(
+      `The public key for signature verification (${kid}) cannot be found in the Entity Configuration`
+    );
+  }
+};
+
+/**
+ * Utility to format flattened Zod errors into a simplified string `key1: key1_error, key2: key2_error`
+ */
+const formatFlattenedZodErrors = (
+  errors: Zod.typeToFlattenedError<RequestObject>
+): string =>
+  Object.entries(errors.fieldErrors)
+    .map(([key, error]) => `${key}: ${error[0]}`)
+    .join(", ");

package/src/credential/presentation/07-evaluate-dcql-query.ts

@@ -1,15 +1,10 @@
-import {
-  DcqlQuery,
-  DcqlError,
-  DcqlCredentialSetError,
-  DcqlQueryResult,
-} from "dcql";
+import { DcqlQuery, DcqlError, DcqlQueryResult } from "dcql";
 import { isValiError } from "valibot";
 import { decode, prepareVpToken } from "../../sd-jwt";
 import type { Disclosure } from "../../sd-jwt/types";
-import { ValidationFailed } from "../../utils/errors";
 import { createCryptoContextFor } from "../../utils/crypto";
 import type { RemotePresentation } from "./types";
+import { CredentialsNotFoundError, type NotFoundDetail } from "./errors";
 
 /**
  * The purpose for the credential request by the RP.
@@ -47,6 +42,11 @@ type DcqlMatchSuccess = Extract<
   { success: true }
 >;
 
+type DcqlMatchFailure = Extract<
+  DcqlQueryResult.CredentialMatch,
+  { success: false }
+>;
+
 /**
  * Convert a credential in JWT format to an object with claims
  * for correct parsing by the `dcql` library.
@@ -81,6 +81,32 @@ const getDcqlQueryMatches = (result: DcqlQueryResult) =>
     ([, match]) => match.success === true
   ) as [string, DcqlMatchSuccess][];
 
+/**
+ * Extract only failed matches from the DCQL query result.
+ */
+const getDcqlQueryFailedMatches = (result: DcqlQueryResult) =>
+  Object.entries(result.credential_matches).filter(
+    ([, match]) => match.success === false
+  ) as [string, DcqlMatchFailure][];
+
+/**
+ * Extract missing credentials from the DCQL query result.
+ * Note: here we are assuming a failed match is a missing credential,
+ * but there might be other reasons for its failure.
+ */
+const extractMissingCredentials = (
+  queryResult: DcqlQueryResult,
+  originalQuery: DcqlQuery
+): NotFoundDetail[] => {
+  return getDcqlQueryFailedMatches(queryResult).map(([id]) => {
+    const credential = originalQuery.credentials.find((c) => c.id === id);
+    if (credential?.format !== "vc+sd-jwt") {
+      throw new Error("Unsupported format"); // TODO [SIW-2082]: support MDOC credentials
+    }
+    return { id, vctValues: credential.meta?.vct_values };
+  });
+};
+
 export const evaluateDcqlQuery: EvaluateDcqlQuery = (
   credentialsSdJwt,
   query
@@ -97,8 +123,11 @@ export const evaluateDcqlQuery: EvaluateDcqlQuery = (
     const queryResult = DcqlQuery.query(parsedQuery, credentials);
 
     if (!queryResult.canBeSatisfied) {
-      throw new Error("No credential can satisfy the provided DCQL query");
+      throw new CredentialsNotFoundError(
+        extractMissingCredentials(queryResult, parsedQuery)
+      );
     }
+
     // Build an object vct:credentialJwt to map matched credentials to their JWT
     const credentialsSdJwtByVct = credentials.reduce(
       (acc, c, i) => ({ ...acc, [c.vct]: credentialsSdJwt[i]! }),
@@ -132,20 +161,16 @@ export const evaluateDcqlQuery: EvaluateDcqlQuery = (
       };
     });
   } catch (error) {
-    // Invalid DCQL query structure
+    // Invalid DCQL query structure. Remap to `DcqlError` for consistency.
     if (isValiError(error)) {
-      throw new ValidationFailed({
-        message: "Invalid DCQL query",
-        reason: error.issues.map((issue) => issue.message).join(", "),
+      throw new DcqlError({
+        message: "Failed to parse the provided DCQL query",
+        code: "PARSE_ERROR",
+        cause: error.issues,
       });
     }
 
-    if (error instanceof DcqlError) {
-      // TODO [SIW-2110]: handle invalid DQCL query or let the error propagate
-    }
-    if (error instanceof DcqlCredentialSetError) {
-      // TODO [SIW-2110]: handle missing credentials or let the error propagate
-    }
+    // Let other errors propagate so they can be caught with `err instanceof DcqlError`
     throw error;
   }
 };

package/src/credential/presentation/07-evaluate-input-descriptor.ts

@@ -3,7 +3,7 @@ import { SdJwt4VC, type DisclosureWithEncoded } from "../../sd-jwt/types";
 import { decode, prepareVpToken } from "../../sd-jwt";
 import { createCryptoContextFor } from "../../utils/crypto";
 import { JSONPath } from "jsonpath-plus";
-import { CredentialNotFoundError, MissingDataError } from "./errors";
+import { CredentialsNotFoundError, MissingDataError } from "./errors";
 import Ajv from "ajv";
 
 const ajv = new Ajv({ allErrors: true });
@@ -291,9 +291,12 @@ export const findCredentialSdJwt = (
     }
   }
 
-  throw new CredentialNotFoundError(
-    "None of the vc+sd-jwt credentials satisfy the requirements."
-  );
+  throw new CredentialsNotFoundError([
+    {
+      id: "",
+      reason: "None of the vc+sd-jwt credentials satisfy the requirements.",
+    },
+  ]);
 };
 
 /**
@@ -325,9 +328,12 @@ export const evaluateInputDescriptors: EvaluateInputDescriptors = async (
     inputDescriptors.map(async (descriptor) => {
       if (descriptor.format?.["vc+sd-jwt"]) {
         if (!decodedSdJwtCredentials.length) {
-          throw new CredentialNotFoundError(
-            "vc+sd-jwt credential is not supported."
-          );
+          throw new CredentialsNotFoundError([
+            {
+              id: descriptor.id,
+              reason: "vc+sd-jwt credential is not supported.",
+            },
+          ]);
         }
 
         const { matchedEvaluation, matchedKeyTag, matchedCredential } =
@@ -341,9 +347,12 @@ export const evaluateInputDescriptors: EvaluateInputDescriptors = async (
         };
       }
 
-      throw new CredentialNotFoundError(
-        `${descriptor.format} format is not supported.`
-      );
+      throw new CredentialsNotFoundError([
+        {
+          id: descriptor.id,
+          reason: `${descriptor.format} format is not supported.`,
+        },
+      ]);
     })
   );
 };
@@ -385,9 +394,12 @@ export const prepareLegacyRemotePresentations: PrepareLegacyRemotePresentations
           };
         }
 
-        throw new CredentialNotFoundError(
-          `${descriptor.format} format is not supported.`
-        );
+        throw new CredentialsNotFoundError([
+          {
+            id: descriptor.id,
+            reason: `${descriptor.format} format is not supported.`,
+          },
+        ]);
       })
     );
   };