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

package/src/credential/offer/v1.3.3/index.ts

@@ -0,0 +1,8 @@
+import type { OfferApi } from "../api";
+import { resolveCredentialOffer } from "./01-resolve-credential-offer";
+import { extractGrantDetails } from "./02-extract-grant-details";
+
+export const Offer: OfferApi = {
+  resolveCredentialOffer,
+  extractGrantDetails,
+};

package/src/credential/presentation/README.md

@@ -48,6 +48,10 @@ The following HTTP errors are mapped to a `RelyingPartyResponseError` with speci
 **Note:** To successfully complete a remote presentation, the Wallet Instance must be in a valid state with a valid Wallet Instance Attestation.
 
 ```ts
+import { IoWallet } from "@pagopa/io-react-native-wallet"
+
+const wallet = new IoWallet({ version: "1.0.0" })
+
 // Retrieve and scan the qr-code, decode it and get its parameters
 const qrCodeParams = decodeQrCode(qrCode)
 
@@ -57,17 +61,17 @@ const {
   client_id,
   request_uri_method,
   state
-} = Credential.Presentation.startFlowFromQR(qrCodeParams);
+} = wallet.RemotePresentation.startFlowFromQR(qrCodeParams);
 
 // Get the Relying Party's Entity Configuration and evaluate trust
-const { rpConf } = await Credential.Presentation.evaluateRelyingPartyTrust(client_id);
+const { rpConf } = await wallet.RemotePresentation.evaluateRelyingPartyTrust(client_id);
 
 // Get the Request Object from the RP
 const { requestObjectEncodedJwt } =
-  await Credential.Presentation.getRequestObject(request_uri);
+  await wallet.RemotePresentation.getRequestObject(request_uri);
 
 // Validate the Request Object
-const { requestObject } = await Credential.Presentation.verifyRequestObject(
+const { requestObject } = await wallet.RemotePresentation.verifyRequestObject(
   requestObjectEncodedJwt,
   { clientId: client_id, rpConf }
 );
@@ -78,7 +82,7 @@ const credentialsSdJwt = [
   ["credential2_keytag", "eyJ0eXAiOiJ2YytzZC1qd3QiLCJhbGciOiJFUzI1NiIsImtpZCI6Ii1GXzZVZ2E4bjNWZWdqWTJVN1lVSEsxekxvYUQtTlBUYzYzUk1JU25MYXcifQ.ew0KIC"]
 ];
 
-const result = Credential.Presentation.evaluateDcqlQuery(
+const result = wallet.RemotePresentation.evaluateDcqlQuery(
   credentialsSdJwt,
   requestObject.dcql_query as DcqlQuery
 );
@@ -91,13 +95,12 @@ const credentialsToPresent = result.map(
 );
 
 const remotePresentations =
-  await Credential.Presentation.prepareRemotePresentations(
+  await wallet.RemotePresentation.prepareRemotePresentations(
     credentialsToPresent,
-    requestObject.nonce,
-    requestObject.client_id
+    requestObject
   );
 
-const authResponse = await Credential.Presentation.sendAuthorizationResponse(
+const authResponse = await wallet.RemotePresentation.sendAuthorizationResponse(
   requestObject,
   remotePresentations,
   rpConf

package/src/credential/presentation/api/01-start-flow.ts

@@ -0,0 +1,18 @@
+import type { PresentationParams } from "./types";
+
+type NullablePresentationParams = {
+  [K in keyof PresentationParams]?: PresentationParams[K] | null;
+};
+
+export interface StartFlowApi {
+  /**
+   * Start a presentation flow by validating the required parameters.
+   * Parameters are extracted from a url encoded in a QR code or in a deep link.
+   * @since 1.0.0
+   *
+   * @param params The QR code parameters to be validated
+   * @returns The validated presentation parameters
+   * @throws {InvalidQRCodeError} if the provided parameters are not valid
+   */
+  startFlowFromQR(params: NullablePresentationParams): PresentationParams;
+}

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

@@ -0,0 +1,19 @@
+import type { RelyingPartyConfig } from "./RelyingPartyConfig";
+
+export interface EvaluateRelyingPartyTrustApi {
+  /**
+   * The Relying Party trust evaluation phase.
+   * Fetch the Relying Party's configuration and verify trust.
+   * @since 1.0.0
+   *
+   * @param rpUrl The base url of the Relying Party
+   * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
+   * @returns The Relying Party's configuration
+   */
+  evaluateRelyingPartyTrust(
+    rpUrl: string,
+    ctx?: { appFetch?: GlobalFetch["fetch"] }
+  ): Promise<{
+    rpConf: RelyingPartyConfig;
+  }>;
+}

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

@@ -0,0 +1,20 @@
+import type { RequestObjectWalletCapabilities } from "./types";
+
+export interface GetRequestObjectApi {
+  /**
+   * Obtain the Request Object for RP authentication. Both the GET and POST `request_uri_method` are supported.
+   * @since 1.0.0
+   *
+   * @param authorizationRequestUrl The authorization URL from the QR code
+   * @param context.walletCapabilities (optional) An object containing the wallet technical capabilities that will be sent with a POST request
+   * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
+   * @returns The Request Object that describes the presentation
+   */
+  getRequestObject(
+    authorizationRequestUrl: string,
+    context?: {
+      appFetch?: GlobalFetch["fetch"];
+      walletCapabilities?: RequestObjectWalletCapabilities;
+    }
+  ): Promise<{ requestObjectEncodedJwt: string }>;
+}

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

@@ -0,0 +1,24 @@
+import type { RelyingPartyConfig } from "./RelyingPartyConfig";
+import type { RequestObject } from "./types";
+
+export interface VerifyRequestObjectApi {
+  /**
+   * Function to verify the Request Object's validity, from the signature to the required properties.
+   * @since 1.0.0
+   *
+   * @param requestObjectEncodedJwt The Request Object in JWT format
+   * @param params.clientId The client ID to verify
+   * @param params.rpConf The Entity Configuration of the Relying Party
+   * @param params.state Optional state
+   * @returns The verified Request Object
+   * @throws {InvalidRequestObjectError} if the Request Object cannot be validated
+   */
+  verifyRequestObject(
+    requestObjectEncodedJwt: string,
+    params: {
+      clientId: string;
+      rpConf: RelyingPartyConfig;
+      state?: string;
+    }
+  ): Promise<{ requestObject: RequestObject }>;
+}

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

@@ -0,0 +1,54 @@
+import type { DcqlQuery } from "dcql";
+import type {
+  Credential4Dcql,
+  CredentialFormat,
+  PresentationFrame,
+} from "./types";
+
+/**
+ * The purpose for the credential request by the RP.
+ */
+export type CredentialPurpose = {
+  required: boolean;
+  description?: string;
+};
+
+export type Disclosure = [
+  string /* salt */,
+  string /* claim name */,
+  unknown /* claim value */,
+];
+
+export type EvaluatedDisclosure = {
+  namespace?: string;
+  name: string;
+  value: unknown;
+};
+
+export interface EvaluateDcqlQueryApi {
+  /**
+   * Evaluate a list of credentials against a DCQL query. The function returns details
+   * on the credential(s) that satisfied the query, with useful metadata to ask the user's consent.
+   * @since 1.0.0
+   *
+   * @param query The DCQL query
+   * @param credentialsSdJwt The list of SD-JWT credentials
+   * @param credentialsMdoc The list of mdoc credentials
+   * @returns Credentials that satisfy the query, with disclosure metadata.
+   * @throws {DcqlError} if the provided DCQL query is not valid
+   */
+  evaluateDcqlQuery(
+    query: DcqlQuery.Input,
+    credentialsSdJwt: Credential4Dcql[],
+    credentialsMdoc?: Credential4Dcql[]
+  ): Promise<
+    ({
+      id: string;
+      credential: string;
+      keyTag: string;
+      requiredDisclosures: EvaluatedDisclosure[];
+      presentationFrame: PresentationFrame;
+      purposes: CredentialPurpose[];
+    } & CredentialFormat)[]
+  >;
+}

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

@@ -0,0 +1,67 @@
+import type {
+  AuthorizationResponse,
+  ErrorResponse,
+  RemotePresentation,
+  RequestObject,
+} from "./types";
+import type { RelyingPartyConfig } from "./RelyingPartyConfig";
+import type { EvaluateDcqlQueryApi } from "./05-evaluate-dcql-query";
+import type { Out } from "../../../../src/utils/misc";
+type FetchContext = { appFetch?: GlobalFetch["fetch"] };
+
+export interface SendAuthorizationResponseApi {
+  /**
+   * 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.
+   */
+  prepareRemotePresentations(
+    credentials: Out<EvaluateDcqlQueryApi["evaluateDcqlQuery"]>,
+    authRequestObject: {
+      nonce: string;
+      clientId: string;
+      responseUri: string;
+    }
+  ): Promise<RemotePresentation>;
+
+  /**
+   * Sends the authorization response containing the VP Token to the Relying Party (RP).
+   * This function completes the presentation flow in an OpenID 4 Verifiable Presentations scenario.
+   * @since 1.0.0
+   *
+   * @param requestObject The request details, including presentation requirements.
+   * @param remotePresentation The presentations to send, each with their VP token
+   * @param rpConf The Relying Party common configuration
+   * @param context Contains optional custom fetch implementation.
+   * @returns Parsed and validated authorization response from the Relying Party.
+   */
+  sendAuthorizationResponse(
+    requestObject: RequestObject,
+    remotePresentation: RemotePresentation,
+    rpConf: RelyingPartyConfig,
+    context?: FetchContext
+  ): Promise<AuthorizationResponse>;
+
+  /**
+   * Sends the authorization error response to the Relying Party (RP).
+   * This function completes the presentation flow in an OpenID 4 Verifiable Presentations scenario.
+   * @since 1.0.0
+   *
+   * @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.
+   */
+  sendAuthorizationErrorResponse(
+    requestObject: RequestObject,
+    error: { error: ErrorResponse; errorDescription: string },
+    context?: FetchContext
+  ): Promise<AuthorizationResponse>;
+}

package/src/credential/presentation/api/RelyingPartyConfig.ts

@@ -0,0 +1,25 @@
+import * as z from "zod";
+import { jsonWebKeySchema } from "@openid-federation/core";
+import { FederationEntityMetadata } from "../../../trust/common/types";
+
+/**
+ * Common Relying Party configuration
+ */
+export type RelyingPartyConfig = z.infer<typeof RelyingPartyConfig>;
+export const RelyingPartyConfig = z.object({
+  subject: z.string().optional(),
+  jwks: z.object({
+    keys: z.array(jsonWebKeySchema),
+  }),
+  // UI (from federation_entity)
+  federation_entity: FederationEntityMetadata,
+  /** @deprecated JARM legacy (v1.0 only) */
+  authorization_encrypted_response_alg: z.string().optional(),
+  /** @deprecated JARM legacy (v1.0 only) */
+  authorization_encrypted_response_enc: z.string().optional(),
+  /** @since 1.3.3 */
+  encrypted_response_enc_values_supported: z
+    .array(z.string())
+    .min(1)
+    .optional(),
+});

package/src/credential/presentation/api/index.ts

@@ -0,0 +1,18 @@
+import type { StartFlowApi } from "./01-start-flow";
+import type { EvaluateRelyingPartyTrustApi } from "./02-evaluate-rp-trust";
+import type { GetRequestObjectApi } from "./03-get-request-object";
+import type { VerifyRequestObjectApi } from "./04-verify-request-object";
+import type { EvaluateDcqlQueryApi } from "./05-evaluate-dcql-query";
+import type { SendAuthorizationResponseApi } from "./06-send-authorization-response";
+import type { RelyingPartyConfig } from "./RelyingPartyConfig";
+
+export interface RemotePresentationApi
+  extends StartFlowApi,
+    EvaluateRelyingPartyTrustApi,
+    GetRequestObjectApi,
+    VerifyRequestObjectApi,
+    EvaluateDcqlQueryApi,
+    SendAuthorizationResponseApi {}
+
+export type { RelyingPartyConfig };
+export * from "./types";

package/src/credential/presentation/api/types.ts

@@ -0,0 +1,129 @@
+import * as z from "zod";
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
+import type { SupportedSdJwtLegacyFormat } from "../../../sd-jwt/types";
+
+export type PresentationParams = z.infer<typeof PresentationParams>;
+export const PresentationParams = z.object({
+  client_id: z.string().nonempty(),
+  request: z.string().optional(),
+  request_uri: z.string().url().optional(),
+  request_uri_method: z.enum(["get", "post"]).optional(),
+  state: z.string().optional(),
+});
+
+export type WalletMetadata = z.infer<typeof WalletMetadata>;
+export const WalletMetadata = z.object({
+  authorization_endpoint: z.string().url(),
+  client_id_schemes_supported: z.array(z.string()).optional(),
+  client_id_prefixes_supported: z.array(z.string()).optional(),
+  response_types_supported: z.array(z.string()).optional(),
+  response_modes_supported: z.array(z.string()).optional(),
+  request_object_signing_alg_values_supported: z.array(z.string()).optional(),
+  vp_formats_supported: z.record(
+    z.string(),
+    z.object({
+      "sd-jwt_alg_values": z.array(z.string()).optional(), // alg_values_supported?
+    })
+  ),
+});
+
+/**
+ * Wallet capabilities that must be submitted to get the Request Object
+ * via POST request when the `request_uri_method` is `post`.
+ */
+export type RequestObjectWalletCapabilities = z.infer<
+  typeof RequestObjectWalletCapabilities
+>;
+export const RequestObjectWalletCapabilities = z.object({
+  wallet_metadata: WalletMetadata,
+  wallet_nonce: z.string().optional(),
+});
+
+/**
+ * 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 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",
+]);
+
+export type AuthorizationResponse = {
+  redirect_uri?: string;
+};
+
+/**
+ * A object that associate the information needed to multiple remote presentation
+ * Used with DCQL queries
+ */
+export type RemotePresentationDetails = {
+  requestedClaims: string[];
+  credentialId: string;
+  vpToken: string;
+};
+
+/**
+ * Common Request Object type, decoupled from specific IT-Wallet versions
+ */
+export type RequestObject = {
+  iss: string;
+  response_uri: string;
+  nonce: string;
+  state: string;
+  client_id: string;
+  dcql_query: Record<string, unknown>;
+  response_type: "vp_token";
+  response_mode: "direct_post.jwt";
+};
+
+/**
+ * A object that associate the information needed to multiple remote presentation
+ */
+export type RemotePresentation = {
+  presentations: {
+    requestedClaims: string[];
+    credentialId: string;
+    format: string;
+    vpToken: string;
+  }[];
+  generatedNonce?: string /* nonce generated by app, used in mdoc presentation */;
+};
+
+/**
+ * A pair that associate a key tag with a credential, used in DCQL queries
+ */
+export type Credential4Dcql = [string /* keyTag */, string /* credential */];
+
+/**
+ * An object that defines claims to disclose. Nested claims must use a nested structure.
+ * @example { name: true, address: { country: true } }
+ */
+export type PresentationFrame = {
+  [k: string]: boolean | undefined | PresentationFrame;
+};
+
+/**
+ * A pair that associate a tokenized Verified Credential with the claims presented or requested to present.
+ */
+export type Presentation = [
+  /* verified credential token */ string,
+  /* claims */ PresentationFrame,
+  /* the context for the key associated to the credential */ CryptoContext,
+];
+
+export type CredentialFormat =
+  | { format: "dc+sd-jwt"; vct: string }
+  | { format: SupportedSdJwtLegacyFormat; vct: string }
+  | { format: "mso_mdoc"; doctype: string };
+
+export type EvaluatedDisclosure = {
+  namespace?: string;
+  name: string;
+  value: unknown;
+};

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

@@ -0,0 +1,116 @@
+import { IoWalletError, serializeAttrs } from "../../../utils/errors";
+import type { SupportedSdJwtLegacyFormat } from "../../../sd-jwt/types";
+export { DcqlError } from "dcql";
+
+/**
+ * An error subclass thrown when auth request decode fail
+ *
+ */
+export class AuthRequestDecodeError extends IoWalletError {
+  code = "ERR_IO_WALLET_AUTHENTICATION_REQUEST_DECODE_FAILED";
+
+  /** The Claim for which the validation failed. */
+  claim: string;
+
+  /** Reason code for the validation failure. */
+  reason: string;
+
+  constructor(
+    message: string,
+    claim: string = "unspecified",
+    reason: string = "unspecified"
+  ) {
+    super(serializeAttrs({ message, claim, reason }));
+    this.claim = claim;
+    this.reason = reason;
+  }
+}
+
+/**
+ * When selecting a public key from an entity configuration, and no one meets the requirements for the scenario
+ *
+ */
+export class NoSuitableKeysFoundInEntityConfiguration extends IoWalletError {
+  code = "ERR_NO_SUITABLE_KEYS_NOT_FOUND";
+
+  /**
+   * @param scenario describe the scenario in which the error arise
+   */
+  constructor(scenario: string) {
+    const message = `Entity configuration do not provide any suitable keys (${scenario}).`;
+    super(message);
+  }
+}
+
+/**
+ * When a QR code is not valid.
+ *
+ */
+export class InvalidQRCodeError extends IoWalletError {
+  code = "ERR_INVALID_QR_CODE";
+
+  /** Detailed reason for the QR code validation failure. */
+  reason: string;
+
+  constructor(reason: string) {
+    super("Invalid QR code");
+    this.reason = reason;
+  }
+}
+
+/**
+ * When the Request Object sent by the Relying Party is not valid
+ */
+export class InvalidRequestObjectError extends IoWalletError {
+  code = "ERR_INVALID_REQUEST_OBJECT";
+
+  /** Detailed reason for the Request Object validation failure. */
+  reason: string;
+
+  constructor(message: string, reason = "unspecified") {
+    super(message);
+    this.reason = reason;
+  }
+}
+
+/**
+ * When some required data is missing to continue because certain attributes are not contained inside the wallet.
+ *
+ */
+export class MissingDataError extends IoWalletError {
+  code = "ERR_MISSING_DATA";
+
+  /**
+   * @param missingAttributes An array or description of the attributes that are missing.
+   */
+  constructor(missingAttributes: string) {
+    const message = `Some required data is missing: ${missingAttributes}.`;
+    super(message);
+  }
+}
+
+export type NotFoundDetail = (
+  | { format: "dc+sd-jwt" | SupportedSdJwtLegacyFormat; vctValues?: string[] }
+  | { format: "mso_mdoc"; doctypeValue?: string }
+) & {
+  id: string;
+  reason?: string;
+  issues?: string[];
+};
+
+/**
+ * Error thrown when one or more credentials cannot be found in the wallet
+ * and the presentation request cannot be satisfied.
+ */
+export class CredentialsNotFoundError extends IoWalletError {
+  code = "ERR_CREDENTIALS_NOT_FOUND";
+  details: NotFoundDetail[];
+
+  /**
+   * @param details The details of the credentials that could not be found.
+   */
+  constructor(details: NotFoundDetail[]) {
+    super("One or more credentials cannot be found in the wallet");
+    this.details = details;
+  }
+}