feat: [SIW-2159] Handle presentation errors (#223)

Co-authored-by: ChrisMattew <[email protected]>

Author: gispada

example/src/screens/PresentationScreen.tsx

@@ -42,13 +42,27 @@ export const PresentationScreen = () => {
         isPresent: !!presentationDetails.redirectUri,
         successMessage: "OK",
       },
+      {
+        title: "PID Remote Cross-Device (Refuse)",
+        onPress: () =>
+          navigation.navigate("QrScanner", {
+            presentationBehavior: "refusalState",
+          }),
+        isLoading: refusalPresentationState.isLoading,
+        hasError: refusalPresentationState.hasError,
+        isDone: refusalPresentationState.isDone,
+        icon: "qrCode",
+      },
     ],
     [
       navigation,
       acceptancePresentationState.hasError,
       acceptancePresentationState.isDone,
       acceptancePresentationState.isLoading,
       presentationDetails.redirectUri,
+      refusalPresentationState.hasError,
+      refusalPresentationState.isDone,
+      refusalPresentationState.isLoading,
     ]
   );
 

example/src/thunks/presentation.ts

@@ -99,6 +99,10 @@ export const remoteCrossDevicePresentationThunk = createAppAsyncThunk<
       .map((c) => [c.keyTag, c.credential]),
   ] as [string, string][];
 
+  if (requestObject.dcql_query && args.allowed === "refusalState") {
+    return processRefusedPresentation(requestObject);
+  }
+
   if (requestObject.dcql_query) {
     return processPresentation(requestObject, rpConf, credentialsSdJwt);
   }
@@ -203,3 +207,16 @@ const processPresentation: ProcessPresentation = async (
     requestedClaims: credentialsToPresent.flatMap((c) => c.requestedClaims),
   };
 };
+
+// Mock an error in the presentation flow
+const processRefusedPresentation = async (requestObject: RequestObject) => {
+  const authResponse =
+    await Credential.Presentation.sendAuthorizationErrorResponse(
+      requestObject,
+      {
+        error: "invalid_request_object",
+        errorDescription: "Mock error during request object validation",
+      }
+    );
+  return { authResponse, requestObject, requestedClaims: [] };
+};

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

@@ -1,3 +1,4 @@
+import { RelyingPartyResponseError } from "../../utils/errors";
 import { hasStatusOrThrow } from "../../utils/misc";
 import { RequestObjectWalletCapabilities } from "./types";
 
@@ -40,7 +41,7 @@ export const getRequestObject: GetRequestObject = async (
       },
       body: formUrlEncodedBody.toString(),
     })
-      .then(hasStatusOrThrow(200))
+      .then(hasStatusOrThrow(200, RelyingPartyResponseError))
       .then((res) => res.text());
 
     return {
@@ -51,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 {

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(", ");

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

@@ -1,13 +1,7 @@
-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";
@@ -167,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;
   }
 };

src/credential/presentation/08-send-authorization-response.ts

@@ -7,12 +7,18 @@ import { hasStatusOrThrow, type Out } from "../../utils/misc";
 import {
   type RemotePresentation,
   DirectAuthorizationBodyPayload,
+  ErrorResponse,
   type LegacyRemotePresentation,
-  LegacyDirectAuthorizationBodyPayload,
 } from "./types";
 import * as z from "zod";
 import type { JWK } from "../../utils/jwk";
 import type { RelyingPartyEntityConfiguration } from "../../trust";
+import {
+  RelyingPartyResponseError,
+  ResponseErrorBuilder,
+  UnexpectedStatusCodeError,
+  RelyingPartyResponseErrorCodes,
+} from "../../utils/errors";
 
 export type AuthorizationResponse = z.infer<typeof AuthorizationResponse>;
 export const AuthorizationResponse = z.object({
@@ -61,7 +67,7 @@ export const choosePublicKeyToEncrypt = (
 export const buildDirectPostJwtBody = async (
   requestObject: Out<VerifyRequestObject>["requestObject"],
   rpConf: RelyingPartyEntityConfiguration["payload"]["metadata"],
-  payload: DirectAuthorizationBodyPayload | LegacyDirectAuthorizationBodyPayload
+  payload: DirectAuthorizationBodyPayload
 ): Promise<string> => {
   type Jwe = ConstructorParameters<typeof EncryptJwe>[1];
 
@@ -98,6 +104,34 @@ export const buildDirectPostJwtBody = async (
   return formBody.toString();
 };
 
+/**
+ * Builds a URL-encoded form body for a direct POST response without encryption.
+ *
+ * @param requestObject - Contains state, nonce, and other relevant info.
+ * @param payload - Object that contains either the VP token to encrypt and the stringified mapping of the credential disclosures or the error code
+ * @returns A URL-encoded string suitable for an `application/x-www-form-urlencoded` POST body.
+ */
+export const buildDirectPostBody = async (
+  requestObject: Out<VerifyRequestObject>["requestObject"],
+  payload: DirectAuthorizationBodyPayload
+): Promise<string> => {
+  const formUrlEncodedBody = new URLSearchParams({
+    ...(requestObject.state && { state: requestObject.state }),
+    ...Object.entries(payload).reduce(
+      (acc, [key, value]) => ({
+        ...acc,
+        [key]:
+          Array.isArray(value) || typeof value === "object"
+            ? JSON.stringify(value)
+            : value,
+      }),
+      {} as Record<string, string>
+    ),
+  });
+
+  return formUrlEncodedBody.toString();
+};
+
 /**
  * Type definition for the function that sends the authorization response
  * to the Relying Party, completing the presentation flow.
@@ -218,5 +252,78 @@ export const sendAuthorizationResponse: SendAuthorizationResponse = async (
   })
     .then(hasStatusOrThrow(200))
     .then((res) => res.json())
-    .then(AuthorizationResponse.parse);
+    .then(AuthorizationResponse.parse)
+    .catch(handleAuthorizationResponseError);
+};
+
+/**
+ * Type definition for the function that sends the authorization response
+ * to the Relying Party, completing the presentation flow.
+ */
+export type SendAuthorizationErrorResponse = (
+  requestObject: Out<VerifyRequestObject>["requestObject"],
+  error: { error: ErrorResponse; errorDescription: string },
+  context?: {
+    appFetch?: GlobalFetch["fetch"];
+  }
+) => Promise<AuthorizationResponse>;
+
+/**
+ * Sends the authorization error response to the Relying Party (RP) using the specified `response_mode`.
+ * This function completes the presentation flow in an OpenID 4 Verifiable Presentations scenario.
+ *
+ * @param requestObject - The request details, including presentation requirements.
+ * @param error - The response error value, with description
+ * @param context - Contains optional custom fetch implementation.
+ * @returns Parsed and validated authorization response from the Relying Party.
+ */
+export const sendAuthorizationErrorResponse: SendAuthorizationErrorResponse =
+  async (
+    requestObject,
+    { error, errorDescription },
+    { appFetch = fetch } = {}
+  ): Promise<AuthorizationResponse> => {
+    const requestBody = await buildDirectPostBody(requestObject, {
+      error,
+      error_description: errorDescription,
+    });
+
+    return await appFetch(requestObject.response_uri, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: requestBody,
+    })
+      .then(hasStatusOrThrow(200, RelyingPartyResponseError))
+      .then((res) => res.json())
+      .then(AuthorizationResponse.parse);
+  };
+
+/**
+ * Handle the the presentation error by mapping it to a custom exception.
+ * If the error is not an instance of {@link UnexpectedStatusCodeError}, it is thrown as is.
+ * @param e - The error to be handled
+ * @throws {RelyingPartyResponseError} with a specific code for more context
+ */
+const handleAuthorizationResponseError = (e: unknown) => {
+  if (!(e instanceof UnexpectedStatusCodeError)) {
+    throw e;
+  }
+
+  throw new ResponseErrorBuilder(RelyingPartyResponseError)
+    .handle(400, {
+      code: RelyingPartyResponseErrorCodes.InvalidAuthorizationResponse,
+      message:
+        "The Authorization Response contains invalid parameters or it is malformed",
+    })
+    .handle(403, {
+      code: RelyingPartyResponseErrorCodes.InvalidAuthorizationResponse,
+      message: "The Authorization Response was forbidden",
+    })
+    .handle("*", {
+      code: RelyingPartyResponseErrorCodes.RelyingPartyGenericError,
+      message: "Unable to successfully send the Authorization Response",
+    })
+    .buildFrom(e);
 };