@pagopa/io-react-native-wallet 0.21.0 → 0.22.0

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

@@ -5,16 +5,16 @@ import {
 } from "@pagopa/io-react-native-jwt";
 import type { AuthorizeAccess } from "./05-authorize-access";
 import type { EvaluateIssuerTrust } from "./02-evaluate-issuer-trust";
-import { hasStatus, type Out } from "../../utils/misc";
+import { hasStatus, safeJsonParse, type Out } from "../../utils/misc";
 import type { StartUserAuthorization } from "./03-start-user-authorization";
 import {
+  CredentialInvalidStatusError,
   CredentialIssuingNotSynchronousError,
-  CredentialNotEntitledError,
   CredentialRequestError,
   UnexpectedStatusCodeError,
   ValidationFailed,
 } from "../../utils/errors";
-import { CredentialResponse } from "./types";
+import { CredentialIssuanceFailureResponse, CredentialResponse } from "./types";
 
 import { createDPopToken } from "../../utils/dpop";
 import uuid from "react-native-uuid";
@@ -157,8 +157,8 @@ export const obtainCredential: ObtainCredential = async (
  * Handle the credential 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 {@link StatusAttestationError} if the status code is different from 404
- * @throws {@link StatusAttestationInvalid} if the status code is 404 (meaning the credential is invalid)
+ * @throws {@link CredentialRequestError} if the status code is different from 404
+ * @throws {@link CredentialInvalidStatusError} if the status code is 404 (meaning the credential is invalid)
  */
 const handleObtainCredentialError = (e: unknown) => {
   if (!(e instanceof UnexpectedStatusCodeError)) {
@@ -174,9 +174,13 @@ const handleObtainCredentialError = (e: unknown) => {
     );
   }
 
-  if (e.statusCode === 404) {
-    throw new CredentialNotEntitledError(
+  if ([403, 404].includes(e.statusCode)) {
+    const maybeError = CredentialIssuanceFailureResponse.safeParse(
+      safeJsonParse(e.responseBody)
+    );
+    throw new CredentialInvalidStatusError(
       "Invalid status found for the given credential",
+      maybeError.success ? maybeError.data.error : "unknown",
       e.message
     );
   }

package/src/credential/issuance/README.md

@@ -43,14 +43,16 @@ graph TD;
 
 A `201 Created` response is returned by the credential issuer when the request has been queued because the credential cannot be issued synchronously. The consumer should try to obtain the credential at a later time.
 
-### 404 Not Found (CredentialNotEntitledError)
+Although `201 Created` is not considered an error, it is mapped as an error in this context in order to handle the case where the credential issuance is not synchronous.
+This allows keeping the flow consistent and handle the case where the credential is not immediately available.
 
-A `404 Not Found` response is returned by the credential issuer when the authenticated user is not entitled to receive the requested credential.
+### 403 Forbidden (CredentialInvalidStatusError)
 
-### 201 Created (CredentialIssuingNotSynchronousError)
+A `403 Forbidden` response is returned by the credential issuer when the requested credential has an invalid status. It might contain more details in the `errorCode` property.
 
-Although `201 Created` is not considered an error, it is mapped as an error in this context in order to handle the case where the credential issuance is not synchronous.
-This allows keeping the flow consistent and handle the case where the credential is not immediately available.
+### 404 Not Found (CredentialInvalidStatusError)
+
+A `404 Not Found` response is returned by the credential issuer when the authenticated user is not entitled to receive the requested credential. It might contain more details in the `errorCode` property.
 
 ## Strong authentication for eID issuance (Query Mode)
 

package/src/credential/issuance/types.ts

@@ -30,3 +30,11 @@ export const ResponseUriResultShape = z.object({
 });
 
 export type ResponseMode = "query" | "form_post.jwt";
+
+export const CredentialIssuanceFailureResponse = z.object({
+  error: z.string(),
+});
+
+export type CredentialIssuanceFailureResponse = z.infer<
+  typeof CredentialIssuanceFailureResponse
+>;

package/src/credential/status/02-status-attestation.ts

@@ -1,15 +1,19 @@
 import {
   getCredentialHashWithouDiscloures,
   hasStatus,
+  safeJsonParse,
   type Out,
 } from "../../utils/misc";
 import type { EvaluateIssuerTrust, ObtainCredential } from "../issuance";
 import { SignJWT, type CryptoContext } from "@pagopa/io-react-native-jwt";
 import uuid from "react-native-uuid";
-import { StatusAttestationResponse } from "./types";
+import {
+  InvalidStatusAttestationResponse,
+  StatusAttestationResponse,
+} from "./types";
 import {
   StatusAttestationError,
-  StatusAttestationInvalid,
+  CredentialInvalidStatusError,
   UnexpectedStatusCodeError,
 } from "../../utils/errors";
 
@@ -29,7 +33,7 @@ export type StatusAttestation = (
  * @param credential - The credential to be verified
  * @param credentialCryptoContext - The credential's crypto context
  * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
- * @throws {@link StatusAttestationInvalid} if the status attestation is invalid and thus the credential is not valid
+ * @throws {@link CredentialInvalidStatusError} if the status attestation is invalid and thus the credential is not valid
  * @throws {@link StatusAttestationError} if an error occurs during the status attestation
  * @returns The credential status attestation
  */
@@ -83,7 +87,7 @@ export const statusAttestation: StatusAttestation = async (
  * If the error is not an instance of {@link UnexpectedStatusCodeError}, it is thrown as is.
  * @param e - The error to be handled
  * @throws {@link StatusAttestationError} if the status code is different from 404
- * @throws {@link StatusAttestationInvalid} if the status code is 404 (meaning the credential is invalid)
+ * @throws {@link CredentialInvalidStatusError} if the status code is 404 (meaning the credential is invalid)
  */
 const handleStatusAttestationError = (e: unknown) => {
   if (!(e instanceof UnexpectedStatusCodeError)) {
@@ -91,8 +95,12 @@ const handleStatusAttestationError = (e: unknown) => {
   }
 
   if (e.statusCode === 404) {
-    throw new StatusAttestationInvalid(
+    const maybeError = InvalidStatusAttestationResponse.safeParse(
+      safeJsonParse(e.responseBody)
+    );
+    throw new CredentialInvalidStatusError(
       "Invalid status found for the given credential",
+      maybeError.success ? maybeError.data.error : "unknown",
       e.message
     );
   }

package/src/credential/status/README.md

@@ -18,7 +18,7 @@ graph TD;
 
 ## Mapped results
 
-### 404 Not Found (StatusAttestationInvalid)
+### 404 Not Found (CredentialInvalidStatusError)
 
 A `404 Not Found` response is returned by the credential issuer when the status attestation is invalid.
 

package/src/credential/status/types.ts

@@ -41,3 +41,18 @@ export const ParsedStatusAttestation = z.object({
     iat: UnixTime,
   }),
 });
+
+/**
+ * Shape from parsing a status attestation response in case of error.
+ */
+export const InvalidStatusAttestationResponse = z.object({
+  error: z.string(),
+});
+
+/**
+ * Type from parsing a status attestation response in case of error.
+ * Inferred from {@link InvalidStatusAttestationResponse}.
+ */
+export type InvalidStatusAttestationResponse = z.infer<
+  typeof InvalidStatusAttestationResponse
+>;

package/src/sd-jwt/index.ts

@@ -3,8 +3,6 @@ import { z } from "zod";
 import { decode as decodeJwt } from "@pagopa/io-react-native-jwt";
 import { verify as verifyJwt } from "@pagopa/io-react-native-jwt";
 import { sha256ToBase64 } from "@pagopa/io-react-native-jwt";
-
-import { decodeBase64 } from "@pagopa/io-react-native-jwt";
 import { Disclosure, SdJwt4VC, type DisclosureWithEncoded } from "./types";
 import { verifyDisclosure } from "./verifier";
 import type { JWK } from "../utils/jwk";
@@ -12,9 +10,11 @@ import {
   ClaimsNotFoundBetweenDislosures,
   ClaimsNotFoundInToken,
 } from "../utils/errors";
+import { Base64 } from "js-base64";
 
 const decodeDisclosure = (encoded: string): DisclosureWithEncoded => {
-  const decoded = Disclosure.parse(JSON.parse(decodeBase64(encoded)));
+  const utf8String = Base64.decode(encoded); // Decode Base64 into UTF-8 string
+  const decoded = Disclosure.parse(JSON.parse(utf8String));
   return { decoded, encoded };
 };
 

package/src/trust/types.ts

@@ -53,6 +53,17 @@ const ClaimsMetadata = z.record(
   })
 );
 
+type IssuanceErrorSupported = z.infer<typeof IssuanceErrorSupported>;
+const IssuanceErrorSupported = z.object({
+  display: z.array(
+    z.object({
+      title: z.string(),
+      description: z.string(),
+      locale: z.string(),
+    })
+  ),
+});
+
 // Metadata for a credentia which is supported by a Issuer
 type SupportedCredentialMetadata = z.infer<typeof SupportedCredentialMetadata>;
 const SupportedCredentialMetadata = z.object({
@@ -63,6 +74,7 @@ const SupportedCredentialMetadata = z.object({
   cryptographic_binding_methods_supported: z.array(z.string()),
   credential_signing_alg_values_supported: z.array(z.string()),
   authentic_source: z.string().optional(),
+  issuance_errors_supported: z.record(IssuanceErrorSupported).optional(),
 });
 
 export type EntityStatement = z.infer<typeof EntityStatement>;

package/src/utils/errors.ts

@@ -1,3 +1,5 @@
+import type { CredentialIssuerEntityConfiguration } from "../trust/types";
+
 /**
  * utility to format a set of attributes into an error message string
  *
@@ -56,8 +58,10 @@ export class UnexpectedStatusCodeError extends IoWalletError {
 
   /** HTTP status code */
   statusCode: number;
+  /** The stringified response body, useful to process the error response */
+  responseBody: string;
 
-  constructor(message: string, statusCode: number) {
+  constructor(message: string, statusCode: number, responseBody: string) {
     super(
       serializeAttrs({
         message,
@@ -65,6 +69,7 @@ export class UnexpectedStatusCodeError extends IoWalletError {
       })
     );
     this.statusCode = statusCode;
+    this.responseBody = responseBody;
   }
 }
 /**
@@ -461,19 +466,28 @@ export class OperationAbortedError extends IoWalletError {
 }
 
 /**
- * Error subclass thrown when the status attestation for a credential is invalid.
+ * Error subclass thrown when a credential status is invalid, either during issuance or when requesting a status attestation.
  */
-export class StatusAttestationInvalid extends IoWalletError {
-  static get code(): "ERR_STATUS_ATTESTATION_INVALID" {
-    return "ERR_STATUS_ATTESTATION_INVALID";
+export class CredentialInvalidStatusError extends IoWalletError {
+  static get code(): "ERR_CREDENTIAL_INVALID_STATUS" {
+    return "ERR_CREDENTIAL_INVALID_STATUS";
   }
 
-  code = "ERR_STATUS_ATTESTATION_INVALID";
+  code = "ERR_CREDENTIAL_INVALID_STATUS";
 
+  /**
+   * The error code that should be mapped with one of the `issuance_errors_supported` in the EC.
+   */
+  errorCode: string;
   reason: string;
 
-  constructor(message: string, reason: string = "unspecified") {
-    super(serializeAttrs({ message, reason }));
+  constructor(
+    message: string,
+    errorCode: string,
+    reason: string = "unspecified"
+  ) {
+    super(serializeAttrs({ message, errorCode, reason }));
+    this.errorCode = errorCode;
     this.reason = reason;
   }
 }
@@ -496,24 +510,6 @@ export class StatusAttestationError extends IoWalletError {
   }
 }
 
-/**
- * Error subclass thrown when the the user is not entitled to receive the requested credential.
- */
-export class CredentialNotEntitledError extends IoWalletError {
-  static get code(): "CREDENTIAL_NOT_ENTITLED_ERROR" {
-    return "CREDENTIAL_NOT_ENTITLED_ERROR";
-  }
-
-  code = "CREDENTIAL_NOT_ENTITLED_ERROR";
-
-  reason: string;
-
-  constructor(message: string, reason: string = "unspecified") {
-    super(serializeAttrs({ message, reason }));
-    this.reason = reason;
-  }
-}
-
 /**
  * Error subclass thrown when an error occurs while requesting a credential.
  */
@@ -549,3 +545,53 @@ export class CredentialIssuingNotSynchronousError extends IoWalletError {
     this.reason = reason;
   }
 }
+
+type LocalizedIssuanceError = {
+  [locale: string]: {
+    title: string;
+    description: string;
+  };
+};
+
+/**
+ * Function to extract the error message from the Entity Configuration's supported error codes.
+ * @param errorCode The error code to map to a meaningful message
+ * @param params.issuerConf The entity configuration for credentials
+ * @param params.credentialType The type of credential the error belongs to
+ * @returns A localized error {@link LocalizedIssuanceError} or undefined
+ * @throws {Error} When no credential config is found
+ */
+export function extractErrorMessageFromIssuerConf(
+  errorCode: string,
+  {
+    issuerConf,
+    credentialType,
+  }: {
+    issuerConf: CredentialIssuerEntityConfiguration["payload"]["metadata"];
+    credentialType: string;
+  }
+): LocalizedIssuanceError | undefined {
+  const credentialConfiguration =
+    issuerConf.openid_credential_issuer.credential_configurations_supported[
+      credentialType
+    ];
+
+  if (!credentialConfiguration) {
+    throw new Error(
+      `No configuration found for ${credentialType} in the provided EC`
+    );
+  }
+
+  const { issuance_errors_supported } = credentialConfiguration;
+
+  if (!issuance_errors_supported?.[errorCode]) {
+    return undefined;
+  }
+
+  const localesList = issuance_errors_supported[errorCode]!.display;
+
+  return localesList.reduce(
+    (acc, { locale, ...rest }) => ({ ...acc, [locale]: rest }),
+    {} as LocalizedIssuanceError
+  );
+}

package/src/utils/misc.ts

@@ -11,11 +11,11 @@ export const hasStatus =
   (status: number) =>
   async (res: Response): Promise<Response> => {
     if (res.status !== status) {
+      const responseBody = await res.text();
       throw new UnexpectedStatusCodeError(
-        `Http request failed. Expected ${status}, got ${res.status}, url: ${
-          res.url
-        } with response: ${await res.text()}`,
-        res.status
+        `Http request failed. Expected ${status}, got ${res.status}, url: ${res.url} with response: ${responseBody}`,
+        res.status,
+        responseBody
       );
     }
     return res;
@@ -109,3 +109,11 @@ export const createAbortPromiseFromSignal = (signal: AbortSignal) => {
 
 export const isDefined = <T>(x: T | undefined | null | ""): x is T =>
   Boolean(x);
+
+export const safeJsonParse = <T>(text: string, withDefault?: T): T | null => {
+  try {
+    return JSON.parse(text);
+  } catch (_) {
+    return withDefault ?? null;
+  }
+};