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

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

@@ -0,0 +1,40 @@
+import * as z from "zod";
+import { UnixTime } from "../../../utils/zod";
+import { ErrorResponse } from "../api/types";
+
+export type RequestObjectPayload = z.infer<typeof RequestObjectPayload>;
+export const RequestObjectPayload = z.object({
+  iss: z.string(),
+  iat: UnixTime,
+  exp: UnixTime,
+  state: z.string(),
+  nonce: z.string(),
+  response_uri: z.string(),
+  request_uri_method: z.string().optional(),
+  response_type: z.literal("vp_token"),
+  response_mode: z.literal("direct_post.jwt"),
+  client_id: z.string(),
+  dcql_query: z.record(z.string(), z.any()), // Validation happens within the `dcql` library, no need to duplicate it here
+  scope: z.string().optional(),
+  wallet_nonce: z.string().optional(),
+});
+
+/**
+ * Authorization Response payload sent to the Relying Party.
+ */
+export type DirectAuthorizationBodyPayload = z.infer<
+  typeof DirectAuthorizationBodyPayload
+>;
+export const DirectAuthorizationBodyPayload = z.union([
+  z.object({
+    vp_token: z.record(z.string(), z.string()),
+  }),
+  z.object({ error: ErrorResponse, error_description: z.string() }),
+]);
+
+export type AuthorizationResponse = z.infer<typeof AuthorizationResponse>;
+export const AuthorizationResponse = z.object({
+  status: z.string().optional(),
+  response_code: z.string().optional(),
+  redirect_uri: z.string().optional(),
+});

package/src/credential/presentation/v1.0.0/utils.jwks.ts

@@ -0,0 +1,26 @@
+import { JWKS, type JWK } from "../../../utils/jwk";
+import type { RelyingPartyConfig } from "../api";
+
+/**
+ * Fetches the JSON Web Key Set (JWKS) from the Relying Party's Entity Configuration.
+ * @param rpConfig - The Relying Party's common configuration,
+ * @returns An object containing an array of JSON Web Keys (JWKs).
+ */
+export const getJwksFromRpConfig = (
+  rpConfig: RelyingPartyConfig
+): { keys: JWK[] } => {
+  const jwks = rpConfig.jwks.keys;
+
+  if (!jwks || !Array.isArray(jwks)) {
+    throw new Error("JWKS not found in Relying Party configuration.");
+  }
+
+  const parsed = JWKS.safeParse({ keys: jwks });
+  if (!parsed.success) {
+    throw new Error(
+      "JWKS contains unsupported or invalid keys (only RSA/EC JWK supported)"
+    );
+  }
+
+  return parsed.data;
+};

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

@@ -0,0 +1,26 @@
+import { JWKS, type JWK } from "../../../utils/jwk";
+import type { RelyingPartyConfig } from "../api";
+
+/**
+ * Fetches the JSON Web Key Set (JWKS) from the Relying Party's Entity Configuration.
+ * @param rpConfig - The Relying Party's common configuration,
+ * @returns An object containing an array of JSON Web Keys (JWKs).
+ */
+export const getJwksFromRpConfig = (
+  rpConfig: RelyingPartyConfig
+): { keys: JWK[] } => {
+  const jwks = rpConfig.jwks.keys;
+
+  if (!jwks || !Array.isArray(jwks)) {
+    throw new Error("JWKS not found in Relying Party configuration.");
+  }
+
+  const parsed = JWKS.safeParse({ keys: jwks });
+  if (!parsed.success) {
+    throw new Error(
+      "JWKS contains unsupported or invalid keys (only RSA/EC JWK supported)"
+    );
+  }
+
+  return parsed.data;
+};

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

@@ -0,0 +1,22 @@
+import { InvalidQRCodeError } from "../common/errors";
+import type { RemotePresentationApi } from "../api";
+import { PresentationParams } from "../api/types";
+import { validateAuthorizationRequestParams } from "@pagopa/io-wallet-oid4vp";
+
+export const startFlowFromQR: RemotePresentationApi["startFlowFromQR"] = (
+  params
+) => {
+  const parsed = PresentationParams.safeParse(params);
+
+  if (!parsed.success) {
+    throw new InvalidQRCodeError(parsed.error.message);
+  }
+
+  try {
+    const validatedParams = validateAuthorizationRequestParams(parsed.data);
+
+    return validatedParams;
+  } catch (e) {
+    throw new InvalidQRCodeError(e instanceof Error ? e.message : String(e));
+  }
+};

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

@@ -0,0 +1,15 @@
+import { getRelyingPartyEntityConfiguration } from "../../../trust/v1.3.3/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 }
+    );
+
+    const rpConf = mapToRelyingPartyConfig(rpEntityConfiguration);
+
+    return { rpConf };
+  };

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

@@ -0,0 +1,28 @@
+import type { RemotePresentationApi } from "../api";
+import { RequestObjectWalletCapabilities } from "../api/types";
+import { fetchAuthorizationRequest as sdkFetchAuthorizationRequest } from "@pagopa/io-wallet-oid4vp";
+import { mapSdkFetchAuthRequestError } from "./sdkErrorMapper";
+
+export const getRequestObject: RemotePresentationApi["getRequestObject"] =
+  async (
+    authorizationRequestUrl,
+    { appFetch = fetch, walletCapabilities } = {}
+  ) => {
+    const walletParams = walletCapabilities
+      ? (() => {
+          const { wallet_metadata, wallet_nonce } =
+            RequestObjectWalletCapabilities.parse(walletCapabilities);
+          return { walletMetadata: wallet_metadata, walletNonce: wallet_nonce };
+        })()
+      : {};
+
+    const result = await sdkFetchAuthorizationRequest({
+      authorizeRequestUrl: authorizationRequestUrl,
+      callbacks: { fetch: appFetch },
+      ...walletParams,
+    }).catch(mapSdkFetchAuthRequestError);
+
+    return {
+      requestObjectEncodedJwt: result.requestObjectJwt,
+    };
+  };

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

@@ -0,0 +1,31 @@
+import type { RemotePresentationApi } from "../api";
+import { parseAuthorizeRequest as sdkParseAuthorizeRequest } from "@pagopa/io-wallet-oid4vp";
+import { partialCallbacks } from "../../../utils/callbacks";
+import { mapToRequestObject } from "./mappers";
+import { mapSdkRequestObjectError } from "./sdkErrorMapper";
+import { InvalidRequestObjectError } from "../common/errors";
+
+export const verifyRequestObject: RemotePresentationApi["verifyRequestObject"] =
+  async (requestObjectEncodedJwt, { clientId, rpConf }) => {
+    const parsedRequestObject = await sdkParseAuthorizeRequest({
+      requestObjectJwt: requestObjectEncodedJwt,
+      callbacks: {
+        verifyJwt: partialCallbacks.verifyJwt,
+      },
+    }).catch(mapSdkRequestObjectError);
+
+    const payload = parsedRequestObject.payload;
+
+    const isClientIdMatch =
+      clientId === payload.client_id && clientId === rpConf.subject;
+
+    if (!isClientIdMatch) {
+      throw new InvalidRequestObjectError(
+        "Client ID does not match Request Object or Entity Configuration"
+      );
+    }
+
+    return {
+      requestObject: mapToRequestObject(payload),
+    };
+  };

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

@@ -0,0 +1,119 @@
+import { DcqlQuery, DcqlError } from "dcql";
+import { isValiError } from "valibot";
+import { CredentialsNotFoundError } from "../common/errors";
+import type { CredentialPurpose } from "../api/05-evaluate-dcql-query";
+import * as mdocUtils from "./utils.mdoc";
+import type { Credential4Dcql, RemotePresentationApi } from "../api";
+import * as sdJwtUtils from "../common/utils/sd-jwt";
+import { getClaimsFromDcqlMatch } from "./utils.mdoc";
+import {
+  extractFailedCredentialsDetails,
+  getDcqlQueryMatches,
+  getPresentationFrameFromDcqlMatch,
+} from "../common/utils/dcql";
+
+export const evaluateDcqlQuery: RemotePresentationApi["evaluateDcqlQuery"] =
+  async (query, credentialsSdJwt, credentialsMdoc = []) => {
+    const credentials = (
+      await Promise.all([
+        sdJwtUtils.mapCredentialsToObj(credentialsSdJwt),
+        mdocUtils.mapCredentialsToObj(credentialsMdoc),
+      ])
+    ).flat();
+
+    // Build a dictionary <id>:<credential> to map DCQL matches with the raw credential
+    const credentialsById = credentials.reduce(
+      (acc, c) => ({
+        ...acc,
+        ["vct" in c ? c.vct : c.doctype]: c.original_credential,
+      }),
+      {} 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;
+
+        if (matchOutput?.credential_format === "dc+sd-jwt") {
+          const { vct } = matchOutput;
+          const [keyTag, credential] = credentialsById[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 }],
+          };
+        }
+
+        if (matchOutput?.credential_format === "mso_mdoc") {
+          const { doctype } = matchOutput;
+          const [keyTag, credential] = credentialsById[doctype]!;
+
+          const requiredDisclosures = mdocUtils.getClaimsFromDcqlMatch(match);
+          const presentationFrame = mdocUtils.getPresentationFrameFromClaims(
+            requiredDisclosures,
+            doctype
+          );
+
+          return {
+            id,
+            doctype,
+            keyTag,
+            format: matchOutput.credential_format,
+            credential,
+            requiredDisclosures,
+            presentationFrame,
+            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.3.3/06-send-authorization-response.ts

@@ -0,0 +1,160 @@
+import {
+  createAuthorizationResponse as sdkCreateAuthorizationResponse,
+  fetchAuthorizationResponse as sdkFetchAuthorizationResponse,
+} from "@pagopa/io-wallet-oid4vp";
+import type { RemotePresentationApi } from "../api";
+import { partialCallbacks } from "../../../utils/callbacks";
+import { mapSdkAuthorizationResponseError } from "./sdkErrorMapper";
+import {
+  generateRandomAlphaNumericString,
+  hasStatusOrThrow,
+} from "../../../utils/misc";
+import {
+  IoWalletError,
+  RelyingPartyResponseError,
+} from "../../../utils/errors";
+import { AuthorizationResponse } from "./types";
+import { buildDirectPostBody } from "../common/utils/http";
+import { prepareVpToken } from "../../../sd-jwt";
+import { createCryptoContextFor } from "../../../utils/crypto";
+import { prepareVpTokenMdoc } from "../../../mdoc";
+
+/**
+ * Prepares remote presentations for a set of credentials.
+ *
+ * For each credential, this function:
+ * - Validates the credential format (currently supports 'mso_mdoc' or 'dc+sd-jwt').
+ * - Generates a verifiable presentation token (vpToken) using the appropriate method.
+ * - For ISO 18013-7, generates a special nonce with minimum entropy of 16.
+ *
+ * @param credentials - An array of credential items containing format, credential data, requested claims, and key information.
+ * @param authRequestObject - The authentication request object containing nonce, clientId, and responseUri.
+ * @returns A promise that resolves to an object containing an array of presentations and the generated nonce.
+ * @throws {CredentialNotFoundError} When the credential format is unsupported.
+ */
+export const prepareRemotePresentations: RemotePresentationApi["prepareRemotePresentations"] =
+  async (credentials, authRequestObject) => {
+    // In case of ISO 18013-7 we need a nonce, it shall have a minimum entropy of 16
+    const generatedNonce = generateRandomAlphaNumericString(16);
+
+    const presentations = await Promise.all(
+      credentials.map(async (item) => {
+        const { format } = item;
+
+        if (format === "dc+sd-jwt") {
+          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,
+          };
+        }
+
+        if (format === "mso_mdoc") {
+          const { vp_token } = await prepareVpTokenMdoc(
+            authRequestObject.nonce,
+            generatedNonce,
+            authRequestObject.clientId,
+            authRequestObject.responseUri,
+            item.doctype,
+            item.keyTag,
+            [
+              item.credential,
+              item.presentationFrame,
+              createCryptoContextFor(item.keyTag),
+            ]
+          );
+
+          return {
+            requestedClaims: item.requiredDisclosures.map(({ name }) => name),
+            credentialId: item.id,
+            vpToken: vp_token,
+            format: "mso_mdoc",
+          };
+        }
+
+        throw new IoWalletError(`${format} format is not supported.`);
+      })
+    );
+
+    return {
+      presentations,
+      generatedNonce,
+    };
+  };
+
+export const sendAuthorizationResponse: RemotePresentationApi["sendAuthorizationResponse"] =
+  async (
+    requestObject,
+    remotePresentation,
+    rpConf,
+    { appFetch = fetch } = {}
+  ) => {
+    try {
+      const { presentations } = remotePresentation;
+      const rpJwks = {
+        jwks: rpConf.jwks,
+        encrypted_response_enc_values_supported:
+          rpConf.encrypted_response_enc_values_supported,
+      };
+
+      const vp_token = presentations.reduce(
+        (acc, p) => {
+          (acc[p.credentialId] ??= []).push(p.vpToken);
+          return acc;
+        },
+        {} as Record<string, string[]>
+      );
+
+      const { jarm } = await sdkCreateAuthorizationResponse({
+        requestObject,
+        rpJwks,
+        vp_token,
+        callbacks: {
+          encryptJwe: partialCallbacks.encryptJwe,
+          generateRandom: partialCallbacks.generateRandom,
+        },
+      });
+
+      return await sdkFetchAuthorizationResponse({
+        authorizationResponseJarm: jarm.responseJwe,
+        presentationResponseUri: requestObject.response_uri,
+        callbacks: { fetch: appFetch },
+      });
+    } catch (err) {
+      throw mapSdkAuthorizationResponseError(err);
+    }
+  };
+
+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);
+  };

package/src/credential/presentation/v1.3.3/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.3.3/mappers.ts

@@ -0,0 +1,34 @@
+import { RelyingPartyEntityConfiguration } from "../../../trust/v1.3.3/types";
+import { createMapper } from "../../../utils/mappers";
+import type { RelyingPartyConfig } from "../api/RelyingPartyConfig";
+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,
+    federation_entity,
+    encrypted_response_enc_values_supported:
+      openid_credential_verifier.encrypted_response_enc_values_supported,
+  };
+});
+
+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,
+}));

package/src/credential/presentation/v1.3.3/sdkErrorMapper.ts

@@ -0,0 +1,93 @@
+import { ValidationError as SdkValidationError } from "@openid4vc/utils";
+import {
+  FetchAuthorizationResponseError as SdkFetchAuthorizationResponseError,
+  CreateAuthorizationResponseError as SdkCreateAuthorizationResponseError,
+} from "@pagopa/io-wallet-oid4vp";
+import {
+  RelyingPartyResponseError,
+  RelyingPartyResponseErrorCodes,
+  ResponseErrorBuilder,
+} from "../../../utils/errors";
+import { Oauth2JwtParseError as SdkOauth2JwtParseError } from "@pagopa/io-wallet-oauth2";
+import { InvalidRequestObjectError } from "../common/errors";
+import { UnexpectedStatusCodeError as SdkUnexpectedStatusCodeError } from "@pagopa/io-wallet-utils";
+import type { RelyingPartyResponseErrorCode } from "src/utils/error-codes";
+
+/**
+ * Helper to create a generic RelyingPartyResponseError
+ */
+const toRelyingPartyResponseError = (
+  message: string,
+  statusCode: number,
+  code: RelyingPartyResponseErrorCode = RelyingPartyResponseErrorCodes.RelyingPartyGenericError
+) =>
+  new RelyingPartyResponseError({
+    code,
+    message,
+    reason: message,
+    statusCode,
+  });
+
+/**
+ * Mapping Sdk errors during Request Object retrieval (Fetch/QR)
+ */
+export const mapSdkFetchAuthRequestError = (err: unknown) => {
+  if (err instanceof SdkUnexpectedStatusCodeError) {
+    throw toRelyingPartyResponseError(err.message, err.statusCode);
+  }
+
+  throw err;
+};
+
+/**
+ * Mapping Sdk errors during JWT parsing and verification
+ */
+export const mapSdkRequestObjectError = (err: unknown) => {
+  if (err instanceof SdkValidationError) {
+    throw new InvalidRequestObjectError(
+      "The Request Object structure is invalid",
+      err.message
+    );
+  }
+
+  if (err instanceof SdkOauth2JwtParseError) {
+    throw new InvalidRequestObjectError(
+      "The Request Object is not a valid JWT"
+    );
+  }
+
+  const message = err instanceof Error ? err.message : String(err);
+  throw new InvalidRequestObjectError(message);
+};
+
+/**
+ * Mapping Sdk errors during Authorization Response submission (JARM / Post)
+ */
+export const mapSdkAuthorizationResponseError = (err: unknown) => {
+  if (err instanceof SdkUnexpectedStatusCodeError) {
+    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(err);
+  }
+
+  if (
+    err instanceof SdkCreateAuthorizationResponseError ||
+    err instanceof SdkFetchAuthorizationResponseError
+  ) {
+    throw toRelyingPartyResponseError(err.message, err.statusCode ?? 400);
+  }
+
+  throw err;
+};

package/src/credential/presentation/v1.3.3/types.ts

@@ -0,0 +1,12 @@
+import * as z from "zod";
+import { zOpenid4vpAuthorizationRequestPayload as sdkRequestObjectPayload } from "@pagopa/io-wallet-oid4vp";
+
+export type RequestObjectPayload = z.infer<typeof sdkRequestObjectPayload>;
+export const RequestObjectPayload = sdkRequestObjectPayload;
+
+export type AuthorizationResponse = z.infer<typeof AuthorizationResponse>;
+export const AuthorizationResponse = z.object({
+  status: z.string().optional(),
+  response_code: z.string().optional(),
+  redirect_uri: z.string().optional(),
+});