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

package/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 {

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,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;
   }
 };

package/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);
 };

package/src/credential/presentation/README.md

@@ -24,10 +24,20 @@ sequenceDiagram
 
 ## Mapped results
 
-|Error|Description|
-|-----|-----------|
-|`ValidationFailed`|The presentation request is not valid, for instance the DCQL query is invalid.|
-|`CredentialsNotFoundError`|The presentation cannot be completed because the Wallet does not contain all requested credentials. The missing credentials can be found in `details`.|
+| Error                       | Description|
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `InvalidRequestObject`      | The Request Object is not valid, for instance it is malformed or its signature cannot be verified.                                                     |
+| `DcqlError`                 | The DCQL query cannot be evaluated because it contains errors.                                                                                         |
+| `CredentialsNotFoundError`  | The presentation cannot be completed because the Wallet does not contain all requested credentials. The missing credentials can be found in `details`. |
+| `RelyingPartyResponseError` | Error in the Relying Party's response. See the next table for more details.                                                                            |
+
+#### RelyingPartyResponseError
+The following HTTP errors are mapped to a `RelyingPartyResponseError` with specific codes.
+
+| HTTP Status  | Error Code                              | Description                                                                                                  |
+| ------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `400`, `403` | `ERR_RP_INVALID_AUTHORIZATION_RESPONSE` | The Relying Party rejected the Authorization Response sent by the Wallet because it was deemed invalid.      |
+| `*`          | `ERR_RP_GENERIC_ERROR`                  | This is a generic error code to map unexpected errors that occurred when interacting with the Relying Party. |
 
 
 ## Examples

package/src/credential/presentation/errors.ts

@@ -1,4 +1,5 @@
 import { IoWalletError, serializeAttrs } from "../../utils/errors";
+export { DcqlError } from "dcql";
 
 /**
  * An error subclass thrown when auth request decode fail
@@ -57,18 +58,17 @@ export class InvalidQRCodeError extends IoWalletError {
 }
 
 /**
- * When the entity is unverified because the Relying Party is not trusted.
- *
+ * When the Request Object sent by the Relying Party is not valid
  */
-export class UnverifiedEntityError extends IoWalletError {
-  code = "ERR_UNVERIFIED_RP_ENTITY";
+export class InvalidRequestObjectError extends IoWalletError {
+  code = "ERR_INVALID_REQUEST_OBJECT";
 
-  /**
-   * @param reason A description of why the entity cannot be verified.
-   */
-  constructor(reason: string) {
-    const message = `Unverified entity: ${reason}.`;
+  /** Detailed reason for the Request Object validation failure. */
+  reason: string;
+
+  constructor(message: string, reason = "unspecified") {
     super(message);
+    this.reason = reason;
   }
 }
 

package/src/credential/presentation/index.ts

@@ -33,6 +33,8 @@ import {
   type SendAuthorizationResponse,
   sendLegacyAuthorizationResponse,
   type SendLegacyAuthorizationResponse,
+  sendAuthorizationErrorResponse,
+  type SendAuthorizationErrorResponse,
 } from "./08-send-authorization-response";
 import * as Errors from "./errors";
 
@@ -49,6 +51,7 @@ export {
   prepareRemotePresentations,
   sendAuthorizationResponse,
   sendLegacyAuthorizationResponse,
+  sendAuthorizationErrorResponse,
   Errors,
 };
 export type {
@@ -64,4 +67,5 @@ export type {
   PrepareRemotePresentations,
   SendAuthorizationResponse,
   SendLegacyAuthorizationResponse,
+  SendAuthorizationErrorResponse,
 };

package/src/credential/presentation/types.ts

@@ -133,26 +133,38 @@ export const RequestObjectWalletCapabilities = z.object({
 });
 
 /**
- * Authorization Response payload when using `presentation_definition`.
- * @deprecated Use `DirectAuthorizationBodyPayload`
+ * This type models the possible error responses the OpenID4VP protocol allows for a presentation of a credential.
+ * When the Wallet encounters one of these errors, it will notify the Relying Party through the `response_uri` endpoint.
+ * See https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/pid-eaa-presentation.html#authorization-response-errors for more information.
  */
-export type LegacyDirectAuthorizationBodyPayload = z.infer<
-  typeof LegacyDirectAuthorizationBodyPayload
->;
+export type ErrorResponse = z.infer<typeof ErrorResponse>;
+export const ErrorResponse = z.enum([
+  "invalid_request_object",
+  "invalid_request_uri",
+  "vp_formats_not_supported",
+  "invalid_request",
+  "access_denied",
+  "invalid_client",
+]);
+
 /**
  * @deprecated Use `DirectAuthorizationBodyPayload`
  */
-export const LegacyDirectAuthorizationBodyPayload = z.object({
+const LegacyDirectAuthorizationBodyPayload = z.object({
   vp_token: z.union([z.string(), z.array(z.string())]).optional(),
   presentation_submission: z.record(z.string(), z.unknown()),
 });
 
 /**
- * Authorization Response payload when using DCQL queries.
+ * Authorization Response payload sent to the Relying Party.
  */
 export type DirectAuthorizationBodyPayload = z.infer<
   typeof DirectAuthorizationBodyPayload
 >;
-export const DirectAuthorizationBodyPayload = z.object({
-  vp_token: z.record(z.string(), z.string()),
-});
+export const DirectAuthorizationBodyPayload = z.union([
+  z.object({
+    vp_token: z.record(z.string(), z.string()),
+  }),
+  z.object({ error: ErrorResponse, error_description: z.string() }),
+  LegacyDirectAuthorizationBodyPayload,
+]);

package/src/utils/error-codes.ts

@@ -43,8 +43,19 @@ export const WalletProviderResponseErrorCodes = {
   WalletInstanceNotFound: "ERR_IO_WALLET_INSTANCE_NOT_FOUND",
 } as const;
 
+export const RelyingPartyResponseErrorCodes = {
+  RelyingPartyGenericError: "ERR_RP_GENERIC_ERROR",
+  /**
+   * An error code thrown then the Relying Party rejects the Wallet's Authorization Response.
+   */
+  InvalidAuthorizationResponse: "ERR_RP_INVALID_AUTHORIZATION_RESPONSE",
+} as const;
+
 export type IssuerResponseErrorCode =
   (typeof IssuerResponseErrorCodes)[keyof typeof IssuerResponseErrorCodes];
 
 export type WalletProviderResponseErrorCode =
   (typeof WalletProviderResponseErrorCodes)[keyof typeof WalletProviderResponseErrorCodes];
+
+export type RelyingPartyResponseErrorCode =
+  (typeof RelyingPartyResponseErrorCodes)[keyof typeof RelyingPartyResponseErrorCodes];

package/src/utils/errors.ts

@@ -3,11 +3,17 @@ import type { CredentialIssuerEntityConfiguration } from "../trust";
 import {
   IssuerResponseErrorCodes,
   WalletProviderResponseErrorCodes,
+  RelyingPartyResponseErrorCodes,
   type IssuerResponseErrorCode,
   type WalletProviderResponseErrorCode,
+  type RelyingPartyResponseErrorCode,
 } from "./error-codes";
 
-export { IssuerResponseErrorCodes, WalletProviderResponseErrorCodes };
+export {
+  IssuerResponseErrorCodes,
+  WalletProviderResponseErrorCodes,
+  RelyingPartyResponseErrorCodes,
+};
 
 // An error reason that supports both a string and a generic JSON object
 type GenericErrorReason = string | Record<string, unknown>;
@@ -110,8 +116,6 @@ export class UnexpectedStatusCodeError extends IoWalletError {
 /**
  * An error subclass thrown when an Issuer HTTP request fails.
  * The specific error can be found in the `code` property.
- *
- * The class is generic over the error code to narrow down the reason.
  */
 export class IssuerResponseError extends UnexpectedStatusCodeError {
   code: IssuerResponseErrorCode;
@@ -149,6 +153,25 @@ export class WalletProviderResponseError extends UnexpectedStatusCodeError {
   }
 }
 
+/**
+ * An error subclass thrown when a Relying Party HTTP request fails.
+ * The specific error can be found in the `code` property.
+ */
+export class RelyingPartyResponseError extends UnexpectedStatusCodeError {
+  code: RelyingPartyResponseErrorCode;
+
+  constructor(params: {
+    code?: RelyingPartyResponseErrorCode;
+    message: string;
+    reason: GenericErrorReason;
+    statusCode: number;
+  }) {
+    super(params);
+    this.code =
+      params.code ?? RelyingPartyResponseErrorCodes.RelyingPartyGenericError;
+  }
+}
+
 type LocalizedIssuanceError = {
   [locale: string]: {
     title: string;
@@ -200,36 +223,43 @@ export function extractErrorMessageFromIssuerConf(
 }
 
 /**
- * Type guard for issuer errors.
- * @param error The error to check
- * @param code Optional code to narrow down the issuer error
+ * Factory function to create a type guard for specific error classes.
+ *
+ * @param errorClass The error class to create the type guard for
+ * @returns A type guard that checks if the error is an instance of the given class and has the expected code
  */
-export const isIssuerResponseError = (
-  error: unknown,
-  code?: IssuerResponseErrorCode
-): error is IssuerResponseError =>
-  error instanceof IssuerResponseError && error.code === (code ?? error.code);
+const makeErrorTypeGuard =
+  <T extends typeof UnexpectedStatusCodeError>(ErrorClass: T) =>
+  (error: unknown, code?: ExtractErrorCode<T>): error is InstanceType<T> =>
+    error instanceof ErrorClass && error.code === (code ?? error.code);
+
+export const isIssuerResponseError = makeErrorTypeGuard(IssuerResponseError);
+export const isWalletProviderResponseError = makeErrorTypeGuard(
+  WalletProviderResponseError
+);
+export const isRelyingPartyResponseError = makeErrorTypeGuard(
+  RelyingPartyResponseError
+);
+
+// Mapping type between error classes and their allowed codes
+type ErrorCodeMap =
+  | {
+      type: typeof IssuerResponseError;
+      code: IssuerResponseErrorCode;
+    }
+  | {
+      type: typeof WalletProviderResponseError;
+      code: WalletProviderResponseErrorCode;
+    }
+  | {
+      type: typeof RelyingPartyResponseError;
+      code: RelyingPartyResponseErrorCode;
+    };
 
-/**
- * Type guard for wallet provider errors.
- * @param error The error to check
- * @param code Optional code to narrow down the wallet provider error
- */
-export const isWalletProviderResponseError = (
-  error: unknown,
-  code?: WalletProviderResponseErrorCode
-): error is WalletProviderResponseError =>
-  error instanceof WalletProviderResponseError &&
-  error.code === (code ?? error.code);
-
-type ErrorCodeMap<T> = T extends typeof IssuerResponseError
-  ? IssuerResponseErrorCode
-  : T extends typeof WalletProviderResponseError
-    ? WalletProviderResponseErrorCode
-    : never;
+type ExtractErrorCode<T> = Extract<ErrorCodeMap, { type: T }>["code"];
 
 type ErrorCase<T> = {
-  code: ErrorCodeMap<T>;
+  code: ExtractErrorCode<T>;
   message: string;
   reason?: GenericErrorReason;
 };