@pagopa/io-react-native-wallet 0.28.1 → 0.28.2

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

@@ -10,6 +10,7 @@ export type EvaluateRelyingPartyTrust = (
   }
 ) => Promise<{
   rpConf: RelyingPartyEntityConfiguration["payload"]["metadata"];
+  subject: string;
 }>;
 
 /**
@@ -25,9 +26,9 @@ export const evaluateRelyingPartyTrust: EvaluateRelyingPartyTrust = async (
   { appFetch = fetch } = {}
 ) => {
   const {
-    payload: { metadata: rpConf },
+    payload: { metadata: rpConf, sub },
   } = await getRelyingPartyEntityConfiguration(rpUrl, {
     appFetch,
   });
-  return { rpConf };
+  return { rpConf, subject: sub };
 };

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

@@ -4,9 +4,8 @@ import { RequestObjectWalletCapabilities } from "./types";
 
 export type GetRequestObject = (
   requestUri: Out<StartFlow>["requestUri"],
-  context: {
+  context?: {
     appFetch?: GlobalFetch["fetch"];
-    walletInstanceAttestation: string;
     walletCapabilities?: RequestObjectWalletCapabilities;
   }
 ) => Promise<{ requestObjectEncodedJwt: string }>;
@@ -23,7 +22,7 @@ export type GetRequestObject = (
  */
 export const getRequestObject: GetRequestObject = async (
   requestUri,
-  { appFetch = fetch, walletCapabilities }
+  { appFetch = fetch, walletCapabilities } = {}
 ) => {
   if (walletCapabilities) {
     // Validate external input

package/src/credential/presentation/05-verify-request-object.ts

@@ -8,8 +8,9 @@ export type VerifyRequestObject = (
   requestObjectEncodedJwt: string,
   context: {
     clientId: string;
-    // jwkKeys: Out<FetchJwks>["keys"];
-    rpConf: RelyingPartyEntityConfiguration["payload"];
+    rpConf: RelyingPartyEntityConfiguration["payload"]["metadata"];
+    rpSubject: string;
+    state?: string;
   }
 ) => Promise<{ requestObject: RequestObject }>;
 
@@ -17,16 +18,16 @@ export type VerifyRequestObject = (
  * Function to verify the Request Object's signature and the client ID.
  * @param requestObjectEncodedJwt The Request Object in JWT format
  * @param context.clientId The client ID to verify
- * @param context.jwkKeys The set of keys to verify the signature
  * @param context.rpConf The Entity Configuration of the Relying Party
+ * @param context.state Optional state
  * @returns The verified Request Object
  */
 export const verifyRequestObject: VerifyRequestObject = async (
   requestObjectEncodedJwt,
-  { clientId, rpConf }
+  { clientId, rpConf, rpSubject, state }
 ) => {
   const requestObjectJwt = decodeJwt(requestObjectEncodedJwt);
-  const { keys } = getJwksFromConfig(rpConf.metadata);
+  const { keys } = getJwksFromConfig(rpConf);
 
   // Verify token signature to ensure the request object is authentic
   const pubKey = keys?.find(
@@ -42,11 +43,21 @@ export const verifyRequestObject: VerifyRequestObject = async (
 
   const requestObject = RequestObject.parse(requestObjectJwt.payload);
 
-  if (!(clientId === requestObject.client_id && clientId === rpConf.sub)) {
+  const isClientIdMatch =
+    clientId === requestObject.client_id && clientId === rpSubject;
+
+  if (!isClientIdMatch) {
     throw new UnverifiedEntityError(
       "Client ID does not match Request Object or Entity Configuration"
     );
   }
 
+  const isStateMatch =
+    state && requestObject.state ? state === requestObject.state : true;
+
+  if (!isStateMatch) {
+    throw new UnverifiedEntityError("State does not match Request Object");
+  }
+
   return { requestObject };
 };

package/src/credential/presentation/07-evaluate-dcql-query.ts

@@ -6,23 +6,32 @@ import {
 } from "dcql";
 import { isValiError } from "valibot";
 import { decode, prepareVpToken } from "../../sd-jwt";
-import type { Disclosure, DisclosureWithEncoded } from "../../sd-jwt/types";
+import type { Disclosure } from "../../sd-jwt/types";
 import { ValidationFailed } from "../../utils/errors";
 import { createCryptoContextFor } from "../../utils/crypto";
 import type { RemotePresentation } from "./types";
 
-type EvaluateDcqlQuery = (
+/**
+ * The purpose for the credential request by the RP.
+ */
+type CredentialPurpose = {
+  required: boolean;
+  description?: string;
+};
+
+export type EvaluateDcqlQuery = (
   credentialsSdJwt: [string /* keyTag */, string /* credential */][],
   query: DcqlQuery.Input
 ) => {
   id: string;
+  vct: string;
   credential: string;
   keyTag: string;
-  requiredDisclosures: DisclosureWithEncoded[];
-  isOptional?: boolean;
+  requiredDisclosures: Disclosure[];
+  purposes: CredentialPurpose[];
 }[];
 
-type PrepareRemotePresentations = (
+export type PrepareRemotePresentations = (
   credentials: {
     id: string;
     credential: string;
@@ -90,7 +99,6 @@ export const evaluateDcqlQuery: EvaluateDcqlQuery = (
     if (!queryResult.canBeSatisfied) {
       throw new Error("No credential can satisfy the provided DCQL query");
     }
-
     // Build an object vct:credentialJwt to map matched credentials to their JWT
     const credentialsSdJwtByVct = credentials.reduce(
       (acc, c, i) => ({ ...acc, [c.vct]: credentialsSdJwt[i]! }),
@@ -103,24 +111,24 @@ export const evaluateDcqlQuery: EvaluateDcqlQuery = (
       }
       const { vct, claims } = match.output;
 
-      // Find a matching credential set to see whether the credential is optional
-      // If no credential set is found, then the credential is required by default
-      // NOTE: This is an extra, it might not be necessary
-      const credentialSet = queryResult.credential_sets?.find((set) =>
-        set.matching_options?.flat().includes(vct)
-      );
-      const isOptional = credentialSet ? !credentialSet.required : false;
+      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 [keyTag, credential] = credentialsSdJwtByVct[vct]!;
-      const requiredDisclosures = Object.values(
-        claims
-      ) as DisclosureWithEncoded[];
+      const requiredDisclosures = Object.values(claims) as Disclosure[];
       return {
         id,
+        vct,
         keyTag,
         credential,
-        isOptional,
         requiredDisclosures,
+        // 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-24.html#section-6.3.1.2-2.1
+        purposes: purposes ?? [{ required: true }],
       };
     });
   } catch (error) {

package/src/credential/presentation/07-evaluate-input-descriptor.ts

@@ -33,7 +33,10 @@ export type EvaluateInputDescriptors = (
   }[]
 >;
 
-export type PrepareRemotePresentations = (
+/**
+ * @deprecated Use `prepareRemotePresentations` from DCQL
+ */
+export type PrepareLegacyRemotePresentations = (
   credentialAndDescriptors: {
     requestedClaims: string[];
     inputDescriptor: InputDescriptor;
@@ -352,6 +355,8 @@ export const evaluateInputDescriptors: EvaluateInputDescriptors = async (
  * - Validates the credential format.
  * - Generates a verifiable presentation token (vpToken) using the provided nonce and client identifier.
  *
+ * @deprecated Use `prepareRemotePresentations` from DCQL
+ *
  * @param credentialAndDescriptors - An array containing objects with requested claims,
  *                                   input descriptor, credential, and keyTag.
  * @param nonce - A unique nonce for the verifiable presentation token.
@@ -359,33 +364,30 @@ export const evaluateInputDescriptors: EvaluateInputDescriptors = async (
  * @returns A promise that resolves to an array of RemotePresentation objects.
  * @throws {CredentialNotFoundError} When the credential format is unsupported.
  */
-export const prepareRemotePresentations: PrepareRemotePresentations = async (
-  credentialAndDescriptors,
-  nonce,
-  client_id
-) => {
-  return Promise.all(
-    credentialAndDescriptors.map(async (item) => {
-      const descriptor = item.inputDescriptor;
-
-      if (descriptor.format?.["vc+sd-jwt"]) {
-        const { vp_token } = await prepareVpToken(nonce, client_id, [
-          item.credential,
-          item.requestedClaims,
-          createCryptoContextFor(item.keyTag),
-        ]);
-
-        return {
-          requestedClaims: item.requestedClaims,
-          inputDescriptor: descriptor,
-          vpToken: vp_token,
-          format: "vc+sd-jwt",
-        };
-      }
+export const prepareLegacyRemotePresentations: PrepareLegacyRemotePresentations =
+  async (credentialAndDescriptors, nonce, client_id) => {
+    return Promise.all(
+      credentialAndDescriptors.map(async (item) => {
+        const descriptor = item.inputDescriptor;
+
+        if (descriptor.format?.["vc+sd-jwt"]) {
+          const { vp_token } = await prepareVpToken(nonce, client_id, [
+            item.credential,
+            item.requestedClaims,
+            createCryptoContextFor(item.keyTag),
+          ]);
+
+          return {
+            requestedClaims: item.requestedClaims,
+            inputDescriptor: descriptor,
+            vpToken: vp_token,
+            format: "vc+sd-jwt",
+          };
+        }
 
-      throw new CredentialNotFoundError(
-        `${descriptor.format} format is not supported.`
-      );
-    })
-  );
-};
+        throw new CredentialNotFoundError(
+          `${descriptor.format} format is not supported.`
+        );
+      })
+    );
+  };

package/src/credential/presentation/08-send-authorization-response.ts

@@ -60,7 +60,7 @@ export const choosePublicKeyToEncrypt = (
  */
 export const buildDirectPostJwtBody = async (
   requestObject: Out<VerifyRequestObject>["requestObject"],
-  rpConf: RelyingPartyEntityConfiguration["payload"],
+  rpConf: RelyingPartyEntityConfiguration["payload"]["metadata"],
   payload: DirectAuthorizationBodyPayload | LegacyDirectAuthorizationBodyPayload
 ): Promise<string> => {
   type Jwe = ConstructorParameters<typeof EncryptJwe>[1];
@@ -70,19 +70,21 @@ export const buildDirectPostJwtBody = async (
     state: requestObject.state,
     ...payload,
   });
-
   // Choose a suitable public key for encryption
-  const { keys } = getJwksFromConfig(rpConf.metadata);
+  const { keys } = getJwksFromConfig(rpConf);
   const encPublicJwk = choosePublicKeyToEncrypt(keys);
 
   // Encrypt the authorization payload
   const {
     authorization_encrypted_response_alg,
     authorization_encrypted_response_enc,
-  } = rpConf.metadata.openid_credential_verifier;
+  } = rpConf.openid_credential_verifier;
+
+  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"]) || "RSA-OAEP-256",
+    alg: (authorization_encrypted_response_alg as Jwe["alg"]) || defaultAlg,
     enc:
       (authorization_encrypted_response_enc as Jwe["enc"]) || "A256CBC-HS512",
     kid: encPublicJwk.kid,
@@ -106,7 +108,7 @@ export type SendLegacyAuthorizationResponse = (
   requestObject: Out<VerifyRequestObject>["requestObject"],
   presentationDefinitionId: string,
   remotePresentations: LegacyRemotePresentation[],
-  rpConf: RelyingPartyEntityConfiguration["payload"],
+  rpConf: RelyingPartyEntityConfiguration["payload"]["metadata"],
   context?: {
     appFetch?: GlobalFetch["fetch"];
   }
@@ -183,7 +185,7 @@ export const sendLegacyAuthorizationResponse: SendLegacyAuthorizationResponse =
 export type SendAuthorizationResponse = (
   requestObject: Out<VerifyRequestObject>["requestObject"],
   remotePresentations: RemotePresentation[],
-  rpConf: RelyingPartyEntityConfiguration["payload"],
+  rpConf: RelyingPartyEntityConfiguration["payload"]["metadata"],
   context?: {
     appFetch?: GlobalFetch["fetch"];
   }

package/src/credential/presentation/README.md

@@ -1,3 +1,89 @@
-# Credential presentation
+# Credential Presentation
 
-Currently this flow is outdated.
+This flow is used for remote presentation, allowing a user with a valid Wallet Instance to remotely present credentials to a Relying Party (Verifier). The presentation flow adheres to the [IT Wallet 0.9.x specification](https://italia.github.io/eid-wallet-it-docs/v0.9.3/en/relying-party-solution.html).
+
+The Relying Party provides the Wallet with a Request Object that contains the requested credentials and claims. The Wallet validates the Request Object and asks the user for consent. Then the Wallet creates an encrypted Authorization Response that contains the Verifiable Presentation with the requested data (`vp_token`) and sends it to the Relying Party.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant I as User (Wallet Instance)
+  participant O as Relying Party (Verifier)
+
+  O->>+I: QR-CODE: Authorization Request (`request_uri`)
+  I->>+O: GET: Verifier's Entity Configuration
+  O->>+I: Respond with metadata (including public keys)
+  I->>+O: GET: Request Object, resolved from the `request_uri`
+  O->>+I: Respond with the Request Object
+  I->>+O: POST: VP token encrypted response
+  O->>+I: Redirect: Authorization Response
+```
+
+
+## Examples
+
+<details>
+  <summary>Remote Presentation flow</summary>
+
+**Note:** To successfully complete a remote presentation, the Wallet Instance must be in a valid state with a valid Wallet Instance Attestation.
+
+```ts
+// Retrieve and scan the qr-code, decode it and get its parameters
+const qrCodeParams = decodeQrCode(qrCode)
+
+// Start the issuance flow
+const {
+  requestUri,
+  clientId,
+  requestUriMethod,
+  state
+} = Credential.Presentation.startFlowFromQR(qrCodeParams);
+
+// Get the Relying Party's Entity Configuration and evaluate trust
+const { rpConf } = await Credential.Presentation.evaluateRelyingPartyTrust(clientId);
+
+// Get the Request Object from the RP
+const { requestObjectEncodedJwt } =
+  await Credential.Presentation.getRequestObject(requestUri);
+
+// Validate the Request Object
+const { requestObject } = await Credential.Presentation.verifyRequestObject(
+  requestObjectEncodedJwt,
+  { clientId, rpConf }
+);
+
+// All the credentials that might be requested by the Relying Party
+const credentialsSdJwt = [
+  ["credential1_keytag", "eyJraWQiOiItRl82VWdhOG4zVmVnalkyVTdZVUhLMXpMb2FELU5QVGM2M1JNSVNuTGF3IiwidHlwIjoidmMrc2Qtand0IiwiYWxnIjoiRVMyNTYifQ.eyJfc2"],
+  ["credential2_keytag", "eyJ0eXAiOiJ2YytzZC1qd3QiLCJhbGciOiJFUzI1NiIsImtpZCI6Ii1GXzZVZ2E4bjNWZWdqWTJVN1lVSEsxekxvYUQtTlBUYzYzUk1JU25MYXcifQ.ew0KIC"]
+];
+
+const result = Credential.Presentation.evaluateDcqlQuery(
+  credentialsSdJwt,
+  requestObject.dcql_query as DcqlQuery
+);
+
+const credentialsToPresent = result.map(
+  ({ requiredDisclosures, ...rest }) => ({
+    ...rest,
+    requestedClaims: requiredDisclosures.map(([, claimName]) => claimName),
+  })
+);
+
+const remotePresentations =
+  await Credential.Presentation.prepareRemotePresentations(
+    credentialsToPresent,
+    requestObject.nonce,
+    requestObject.client_id
+  );
+
+const authResponse = await Credential.Presentation.sendAuthorizationResponse(
+  requestObject,
+  remotePresentations,
+  rpConf
+);
+```
+
+</details>

package/src/credential/presentation/errors.ts

@@ -47,12 +47,12 @@ export class NoSuitableKeysFoundInEntityConfiguration extends IoWalletError {
 export class InvalidQRCodeError extends IoWalletError {
   code = "ERR_INVALID_QR_CODE";
 
-  /**
-   * @param detail A description of why the QR code is considered invalid.
-   */
-  constructor(detail: string) {
-    const message = `QR code is not valid: ${detail}.`;
-    super(message);
+  /** Detailed reason for the QR code validation failure. */
+  reason: string;
+
+  constructor(reason: string) {
+    super("Invalid QR code");
+    this.reason = reason;
   }
 }
 

package/src/credential/presentation/index.ts

@@ -17,12 +17,22 @@ import {
   type FetchPresentationDefinition,
 } from "./06-fetch-presentation-definition";
 import {
-  evaluateInputDescriptorForSdJwt4VC,
-  type EvaluateInputDescriptorSdJwt4VC,
+  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,
 } from "./08-send-authorization-response";
 import * as Errors from "./errors";
 
@@ -33,8 +43,12 @@ export {
   getJwksFromConfig,
   verifyRequestObject,
   fetchPresentDefinition,
-  evaluateInputDescriptorForSdJwt4VC,
+  evaluateInputDescriptors,
+  evaluateDcqlQuery,
+  prepareLegacyRemotePresentations,
+  prepareRemotePresentations,
   sendAuthorizationResponse,
+  sendLegacyAuthorizationResponse,
   Errors,
 };
 export type {
@@ -44,6 +58,10 @@ export type {
   FetchJwks,
   VerifyRequestObject,
   FetchPresentationDefinition,
-  EvaluateInputDescriptorSdJwt4VC,
+  EvaluateInputDescriptors,
+  EvaluateDcqlQuery,
+  PrepareLegacyRemotePresentations,
+  PrepareRemotePresentations,
   SendAuthorizationResponse,
+  SendLegacyAuthorizationResponse,
 };

package/src/credential/presentation/types.ts

@@ -94,7 +94,7 @@ export const RequestObject = z.object({
   iss: z.string(),
   iat: UnixTime,
   exp: UnixTime,
-  state: z.string(),
+  state: z.string().optional(),
   nonce: z.string(),
   response_uri: z.string(),
   response_uri_method: z.string().optional(),