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

package/src/credential/presentation/common/utils.ts

@@ -0,0 +1,30 @@
+import type { RequestObject } from "../api";
+import type { DirectAuthorizationBodyPayload } from "../v1.0.0/types";
+
+/**
+ * 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: RequestObject,
+  payload: DirectAuthorizationBodyPayload
+): Promise<string> => {
+  const formUrlEncodedBody = new URLSearchParams({
+    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();
+};

package/src/credential/presentation/index.ts

@@ -1,71 +1,5 @@
-import { startFlowFromQR, type StartFlow } from "./01-start-flow";
-import {
-  evaluateRelyingPartyTrust,
-  type EvaluateRelyingPartyTrust,
-} from "./02-evaluate-rp-trust";
-import {
-  getRequestObject,
-  type GetRequestObject,
-} from "./03-get-request-object";
-import { getJwksFromConfig, type FetchJwks } from "./04-retrieve-rp-jwks";
-import {
-  verifyRequestObject,
-  type VerifyRequestObject,
-} from "./05-verify-request-object";
-import {
-  fetchPresentDefinition,
-  type FetchPresentationDefinition,
-} from "./06-fetch-presentation-definition";
-import {
-  evaluateInputDescriptors,
-  prepareLegacyRemotePresentations,
-  type EvaluateInputDescriptors,
-  type PrepareLegacyRemotePresentations,
-} from "./07-evaluate-input-descriptor";
-import {
-  evaluateDcqlQuery,
-  prepareRemotePresentations,
-  type EvaluateDcqlQuery,
-  type PrepareRemotePresentations,
-} from "./07-evaluate-dcql-query";
-import {
-  sendAuthorizationResponse,
-  type SendAuthorizationResponse,
-  sendLegacyAuthorizationResponse,
-  type SendLegacyAuthorizationResponse,
-  sendAuthorizationErrorResponse,
-  type SendAuthorizationErrorResponse,
-} from "./08-send-authorization-response";
-import * as Errors from "./errors";
-
-export {
-  startFlowFromQR,
-  evaluateRelyingPartyTrust,
-  getRequestObject,
-  getJwksFromConfig,
-  verifyRequestObject,
-  fetchPresentDefinition,
-  evaluateInputDescriptors,
-  evaluateDcqlQuery,
-  prepareLegacyRemotePresentations,
-  prepareRemotePresentations,
-  sendAuthorizationResponse,
-  sendLegacyAuthorizationResponse,
-  sendAuthorizationErrorResponse,
-  Errors,
-};
-export type {
-  StartFlow,
-  EvaluateRelyingPartyTrust,
-  GetRequestObject,
-  FetchJwks,
-  VerifyRequestObject,
-  FetchPresentationDefinition,
-  EvaluateInputDescriptors,
-  EvaluateDcqlQuery,
-  PrepareLegacyRemotePresentations,
-  PrepareRemotePresentations,
-  SendAuthorizationResponse,
-  SendLegacyAuthorizationResponse,
-  SendAuthorizationErrorResponse,
-};
+import * as Errors from "./common/errors";
+export { Errors };
+export type * from "./api";
+export { RemotePresentation as V1_0_0 } from "./v1.0.0";
+export { RemotePresentation as V1_3_3 } from "./v1.3.3";

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

@@ -0,0 +1,22 @@
+import { InvalidQRCodeError } from "../common/errors";
+import type { RemotePresentationApi } from "../api";
+import { PresentationParams } from "../api/types";
+
+export const startFlowFromQR: RemotePresentationApi["startFlowFromQR"] = (
+  params
+) => {
+  const result = PresentationParams.safeParse({
+    ...params,
+    request_uri_method: params.request_uri_method ?? "get",
+  });
+
+  if (!result.success) throw new InvalidQRCodeError(result.error.message);
+
+  if (!result.data.request_uri) {
+    throw new InvalidQRCodeError(
+      "Invalid QR code missing the required 'request_uri' parameter."
+    );
+  }
+
+  return result.data;
+};

package/src/credential/presentation/v1.0.0/02-evaluate-rp-trust.ts

@@ -0,0 +1,14 @@
+import { getRelyingPartyEntityConfiguration } from "../../../trust/v1.0.0/entities";
+import type { RemotePresentationApi } from "../api";
+import { mapToRelyingPartyConfig } from "./mappers";
+
+export const evaluateRelyingPartyTrust: RemotePresentationApi["evaluateRelyingPartyTrust"] =
+  async (rpUrl, { appFetch = fetch } = {}) => {
+    const rpEntityConfiguration = await getRelyingPartyEntityConfiguration(
+      rpUrl,
+      { appFetch }
+    );
+    return {
+      rpConf: mapToRelyingPartyConfig(rpEntityConfiguration),
+    };
+  };

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

@@ -0,0 +1,61 @@
+import { RelyingPartyResponseError } from "../../../utils/errors";
+import { hasStatusOrThrow } from "../../../utils/misc";
+import type { RemotePresentationApi } from "../api";
+import { RequestObjectWalletCapabilities } from "../api/types";
+import { InvalidQRCodeError } from "../common/errors";
+
+export const getRequestObject: RemotePresentationApi["getRequestObject"] =
+  async (
+    authorizationRequestUrl,
+    { appFetch = fetch, walletCapabilities } = {}
+  ) => {
+    const authorizationUrl = new URL(authorizationRequestUrl);
+
+    /*
+     * The QR code parameters are validated in step 1.
+     * For consistency with the 1.3 flow we accept the full authorization URL,
+     * but here we only extract the `request_uri` to retrieve the Request Object.
+     */
+    const requestUri =
+      authorizationUrl.searchParams.get("request_uri") ?? undefined;
+    if (!requestUri) {
+      throw new InvalidQRCodeError(
+        "The QR code is missing the required 'request_uri' parameter."
+      );
+    }
+
+    if (walletCapabilities) {
+      // Validate external input
+      const { wallet_metadata, wallet_nonce } =
+        RequestObjectWalletCapabilities.parse(walletCapabilities);
+
+      const formUrlEncodedBody = new URLSearchParams({
+        wallet_metadata: JSON.stringify(wallet_metadata),
+        ...(wallet_nonce && { wallet_nonce }),
+      });
+
+      const requestObjectEncodedJwt = await appFetch(requestUri, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: formUrlEncodedBody.toString(),
+      })
+        .then(hasStatusOrThrow(200, RelyingPartyResponseError))
+        .then((res) => res.text());
+
+      return {
+        requestObjectEncodedJwt,
+      };
+    }
+
+    const requestObjectEncodedJwt = await appFetch(requestUri, {
+      method: "GET",
+    })
+      .then(hasStatusOrThrow(200, RelyingPartyResponseError))
+      .then((res) => res.text());
+
+    return {
+      requestObjectEncodedJwt,
+    };
+  };

package/src/credential/presentation/v1.0.0/04-verify-request-object.ts

@@ -0,0 +1,104 @@
+import { decode as decodeJwt, verify } from "@pagopa/io-react-native-jwt";
+import { type typeToFlattenedError } from "zod";
+import type { RelyingPartyConfig, RemotePresentationApi } from "../api";
+import { InvalidRequestObjectError } from "../common/errors";
+import { RequestObjectPayload } from "./types";
+import { mapToRequestObject } from "./mappers";
+import { getJwksFromRpConfig } from "./utils.jwks";
+
+export const verifyRequestObject: RemotePresentationApi["verifyRequestObject"] =
+  async (requestObjectEncodedJwt, { clientId, rpConf, state }) => {
+    const requestObjectJwt = decodeJwt(requestObjectEncodedJwt);
+
+    const pubKey = getSigPublicKey(
+      rpConf,
+      requestObjectJwt.protectedHeader.kid
+    );
+
+    try {
+      // Standard claims are verified within `verify`
+      await verify(requestObjectEncodedJwt, pubKey, { issuer: clientId });
+    } catch (_) {
+      throw new InvalidRequestObjectError(
+        "The Request Object signature verification failed"
+      );
+    }
+
+    const requestObject = validateRequestObjectShape(requestObjectJwt.payload);
+
+    const isClientIdMatch =
+      clientId === requestObject.client_id && clientId === rpConf.subject;
+
+    if (!isClientIdMatch) {
+      throw new InvalidRequestObjectError(
+        "Client ID does not match Request Object or Entity Configuration"
+      );
+    }
+
+    const isStateMatch = state ? state === requestObject.state : true;
+
+    if (!isStateMatch) {
+      throw new InvalidRequestObjectError(
+        "The provided state does not match the Request Object's"
+      );
+    }
+
+    return { requestObject: mapToRequestObject(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): RequestObjectPayload => {
+  const requestObjectParse = RequestObjectPayload.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: RelyingPartyConfig,
+  kid: string | undefined
+) => {
+  try {
+    const { keys } = getJwksFromRpConfig(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: typeToFlattenedError<RequestObjectPayload>
+): string =>
+  Object.entries(errors.fieldErrors)
+    .map(([key, error]) => `${key}: ${error[0]}`)
+    .join(", ");

package/src/credential/presentation/v1.0.0/05-evaluate-dcql-query.ts

@@ -0,0 +1,97 @@
+import { DcqlQuery, DcqlError } from "dcql";
+import { isValiError } from "valibot";
+import { CredentialsNotFoundError } from "../common/errors";
+import type { Credential4Dcql, RemotePresentationApi } from "../api";
+import type { CredentialPurpose } from "../api/05-evaluate-dcql-query";
+import * as sdJwtUtils from "../common/utils/sd-jwt";
+import {
+  extractFailedCredentialsDetails,
+  getClaimsFromDcqlMatch,
+  getDcqlQueryMatches,
+  getPresentationFrameFromDcqlMatch,
+} from "../common/utils/dcql";
+import { LEGACY_SD_JWT } from "../../../sd-jwt/types";
+
+export const evaluateDcqlQuery: RemotePresentationApi["evaluateDcqlQuery"] =
+  async (query, credentialsSdJwt) => {
+    const credentials = await sdJwtUtils.mapCredentialsToObj(credentialsSdJwt);
+
+    const credentialsByVct = credentials.reduce(
+      (acc, c) => {
+        acc[c.vct] = c.original_credential;
+        return acc;
+      },
+      {} as Record<string, Credential4Dcql>
+    );
+
+    try {
+      // Validate the query
+      const parsedQuery = DcqlQuery.parse(query);
+      DcqlQuery.validate(parsedQuery);
+
+      const queryResult = DcqlQuery.query(parsedQuery, credentials);
+
+      if (!queryResult.can_be_satisfied) {
+        throw new CredentialsNotFoundError(
+          extractFailedCredentialsDetails(queryResult)
+        );
+      }
+
+      return getDcqlQueryMatches(queryResult).map(([id, match]) => {
+        const purposes = queryResult.credential_sets
+          ?.filter((set) => set.matching_options?.flat().includes(id))
+          ?.map<CredentialPurpose>((credentialSet) => ({
+            description: credentialSet.purpose?.toString(),
+            required: Boolean(credentialSet.required),
+          }));
+
+        const matchOutput = match.valid_credentials[0]?.meta.output;
+
+        // The legacy SD-JWT format is still supported because `evaluateDcqlQuery`
+        // is also used when presenting the legacy 0.7.1 eID to get other credentials.
+        if (
+          matchOutput?.credential_format === "dc+sd-jwt" ||
+          (matchOutput?.credential_format === LEGACY_SD_JWT &&
+            "vct" in matchOutput)
+        ) {
+          const { vct } = matchOutput;
+          const [keyTag, credential] = credentialsByVct[vct]!;
+
+          const requiredDisclosures = getClaimsFromDcqlMatch(match);
+          const presentationFrame = getPresentationFrameFromDcqlMatch(
+            match,
+            parsedQuery
+          );
+
+          return {
+            id,
+            vct,
+            keyTag,
+            format: matchOutput.credential_format,
+            credential,
+            requiredDisclosures,
+            presentationFrame,
+            // When it is a match but no credential_sets are found, the credential is required by default
+            // See https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#section-6.4.2
+            purposes: purposes ?? [{ required: true }],
+          };
+        }
+
+        throw new Error(
+          `Unsupported credential format: ${matchOutput?.credential_format}`
+        );
+      });
+    } catch (error) {
+      // Invalid DCQL query structure. Remap to `DcqlError` for consistency.
+      if (isValiError(error)) {
+        throw new DcqlError({
+          message: "Failed to parse the provided DCQL query",
+          code: "PARSE_ERROR",
+          cause: error.issues,
+        });
+      }
+
+      // Let other errors propagate so they can be caught with `err instanceof DcqlError`
+      throw error;
+    }
+  };

package/src/credential/presentation/v1.0.0/06-send-authorization-response.ts

@@ -0,0 +1,196 @@
+import { EncryptJwe } from "@pagopa/io-react-native-jwt";
+import { NoSuitableKeysFoundInEntityConfiguration } from "../common/errors";
+import { hasStatusOrThrow } from "../../../utils/misc";
+import type { JWK } from "../../../utils/jwk";
+import {
+  RelyingPartyResponseError,
+  RelyingPartyResponseErrorCodes,
+  ResponseErrorBuilder,
+  UnexpectedStatusCodeError,
+} from "../../../utils/errors";
+import { prepareVpToken } from "../../../sd-jwt";
+import type { RequestObject } from "../api/types";
+import type { RelyingPartyConfig, RemotePresentationApi } from "../api";
+import { AuthorizationResponse, DirectAuthorizationBodyPayload } from "./types";
+import { getJwksFromRpConfig } from "./utils.jwks";
+import { buildDirectPostBody } from "../common/utils/http";
+import { createCryptoContextFor } from "../../../utils/crypto";
+
+/**
+ * Selects a public key (with `use = enc`) from the set of JWK keys
+ * offered by the Relying Party (RP) for encryption.
+ *
+ * @param rpJwkKeys - The array of JWKs retrieved from the RP entity configuration.
+ * @returns The first suitable public key found in the list.
+ * @throws {NoSuitableKeysFoundInEntityConfiguration} If no suitable encryption key is found.
+ */
+export const choosePublicKeyToEncrypt = (rpJwkKeys: JWK[]): JWK => {
+  const encKey = rpJwkKeys.find((jwk) => jwk.use === "enc");
+
+  if (encKey) {
+    return encKey;
+  }
+
+  // No suitable key found
+  throw new NoSuitableKeysFoundInEntityConfiguration(
+    "No suitable public key found for encryption."
+  );
+};
+
+/**
+ * Builds a URL-encoded form body for a direct POST response using JWT encryption.
+ *
+ * @param jwkKeys - Array of JWKs from the Relying Party for encryption.
+ * @param requestObject - Contains state, nonce, and other relevant info.
+ * @param payload - Object that contains the VP token to encrypt and the mapping of the credential disclosures
+ * @returns A URL-encoded string for an `application/x-www-form-urlencoded` POST body, where `response` contains the encrypted JWE.
+ */
+export const buildDirectPostJwtBody = async (
+  requestObject: RequestObject,
+  rpConf: RelyingPartyConfig,
+  payload: DirectAuthorizationBodyPayload
+): Promise<string> => {
+  type Jwe = ConstructorParameters<typeof EncryptJwe>[1];
+
+  // Prepare the authorization response payload to be encrypted
+  const authzResponsePayload = JSON.stringify({
+    state: requestObject.state,
+    ...payload,
+  });
+  // Choose a suitable public key for encryption
+  const { keys } = getJwksFromRpConfig(rpConf);
+  const encPublicJwk = choosePublicKeyToEncrypt(keys);
+
+  // Encrypt the authorization payload
+  const {
+    authorization_encrypted_response_alg,
+    authorization_encrypted_response_enc,
+  } = rpConf;
+
+  const defaultAlg: Jwe["alg"] =
+    encPublicJwk.kty === "EC" ? "ECDH-ES" : "RSA-OAEP-256";
+
+  const encryptedResponse = await new EncryptJwe(authzResponsePayload, {
+    alg: (authorization_encrypted_response_alg as Jwe["alg"]) || defaultAlg,
+    enc:
+      (authorization_encrypted_response_enc as Jwe["enc"]) || "A256CBC-HS512",
+    kid: encPublicJwk.kid,
+  }).encrypt(encPublicJwk);
+
+  // Build the x-www-form-urlencoded form body
+  const formBody = new URLSearchParams({
+    response: encryptedResponse,
+    state: requestObject.state,
+  });
+  return formBody.toString();
+};
+
+export const prepareRemotePresentations: RemotePresentationApi["prepareRemotePresentations"] =
+  async (credentials, authRequestObject) => {
+    const presentations = await Promise.all(
+      credentials.map(async (item) => {
+        const { vp_token } = await prepareVpToken(
+          authRequestObject.nonce,
+          authRequestObject.clientId,
+          [
+            item.credential,
+            item.presentationFrame,
+            createCryptoContextFor(item.keyTag),
+          ]
+        );
+
+        return {
+          requestedClaims: item.requiredDisclosures.map(({ name }) => name),
+          credentialId: item.id,
+          vpToken: vp_token,
+          format: item.format,
+        };
+      })
+    );
+
+    return { presentations };
+  };
+
+export const sendAuthorizationResponse: RemotePresentationApi["sendAuthorizationResponse"] =
+  async (
+    requestObject,
+    remotePresentation,
+    rpConf,
+    { appFetch = fetch } = {}
+  ) => {
+    const { presentations } = remotePresentation;
+    // 1. Prepare the VP token as a JSON object with keys corresponding to the DCQL query credential IDs
+    const requestBody = await buildDirectPostJwtBody(requestObject, rpConf, {
+      vp_token: presentations.reduce(
+        (acc, presentation) => ({
+          ...acc,
+          [presentation.credentialId]: presentation.vpToken,
+        }),
+        {} as Record<string, string>
+      ),
+    });
+
+    // 2. Send the authorization response via HTTP POST and validate the response
+    return await appFetch(requestObject.response_uri, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: requestBody,
+    })
+      .then(hasStatusOrThrow(200))
+      .then((res) => res.json())
+      .then(AuthorizationResponse.parse)
+      .catch(handleAuthorizationResponseError);
+  };
+
+export const sendAuthorizationErrorResponse: RemotePresentationApi["sendAuthorizationErrorResponse"] =
+  async (
+    requestObject,
+    { error, errorDescription },
+    { appFetch = fetch } = {}
+  ) => {
+    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/v1.0.0/index.ts

@@ -0,0 +1,22 @@
+import type { RemotePresentationApi } from "../api";
+import { startFlowFromQR } from "./01-start-flow";
+import { evaluateRelyingPartyTrust } from "./02-evaluate-rp-trust";
+import { getRequestObject } from "./03-get-request-object";
+import { verifyRequestObject } from "./04-verify-request-object";
+import { evaluateDcqlQuery } from "./05-evaluate-dcql-query";
+import {
+  prepareRemotePresentations,
+  sendAuthorizationResponse,
+  sendAuthorizationErrorResponse,
+} from "./06-send-authorization-response";
+
+export const RemotePresentation: RemotePresentationApi = {
+  startFlowFromQR,
+  evaluateRelyingPartyTrust,
+  getRequestObject,
+  verifyRequestObject,
+  evaluateDcqlQuery,
+  prepareRemotePresentations,
+  sendAuthorizationResponse,
+  sendAuthorizationErrorResponse,
+};

package/src/credential/presentation/v1.0.0/mappers.ts

@@ -0,0 +1,35 @@
+import { createMapper } from "../../../utils/mappers";
+import { RelyingPartyEntityConfiguration } from "../../../trust/v1.0.0/types";
+import type { RelyingPartyConfig } from "../api";
+import type { RequestObject } from "../api/types";
+import { RequestObjectPayload } from "./types";
+
+export const mapToRelyingPartyConfig = createMapper<
+  RelyingPartyEntityConfiguration,
+  RelyingPartyConfig
+>((x) => {
+  const { federation_entity, openid_credential_verifier } = x.payload.metadata;
+  return {
+    subject: x.payload.sub,
+    jwks: openid_credential_verifier.jwks,
+    authorization_encrypted_response_alg:
+      openid_credential_verifier.authorization_encrypted_response_alg,
+    authorization_encrypted_response_enc:
+      openid_credential_verifier.authorization_encrypted_response_enc,
+    federation_entity,
+  };
+});
+
+export const mapToRequestObject = createMapper<
+  RequestObjectPayload,
+  RequestObject
+>((x) => ({
+  iss: x.iss,
+  client_id: x.client_id,
+  dcql_query: x.dcql_query,
+  nonce: x.nonce,
+  response_uri: x.response_uri,
+  state: x.state,
+  response_mode: x.response_mode,
+  response_type: x.response_type,
+}));