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

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(),
+});

package/src/credential/presentation/v1.3.3/utils.mdoc.ts

@@ -0,0 +1,98 @@
+import { CBOR } from "@pagopa/io-react-native-iso18013";
+import { b64utob64 } from "jsrsasign";
+import type { DcqlMdocCredential, DcqlQueryResult } from "dcql";
+import type {
+  Credential4Dcql,
+  EvaluatedDisclosure,
+  PresentationFrame,
+} from "../api";
+import { getValidDcqlClaims } from "../common/utils/dcql";
+
+type CustomDcqlMdocCredential = DcqlMdocCredential & {
+  original_credential: Credential4Dcql;
+};
+
+/**
+ * Convert a list of credential in mdoc format to a list of objects
+ * with namespaces for correct parsing by the `dcql` library.
+ * @param credentials The raw mdoc credentials
+ * @returns List of `dcql` compatible objects
+ */
+export const mapCredentialsToObj = async (
+  credentialsMdoc: Credential4Dcql[]
+): Promise<CustomDcqlMdocCredential[]> => {
+  return await Promise.all(
+    credentialsMdoc.map(async (credential) => {
+      const issuerSigned = await CBOR.decodeIssuerSigned(
+        b64utob64(credential[1])
+      );
+
+      const namespaces = Object.entries(issuerSigned.nameSpaces).reduce(
+        (acc, [ns, nsClaims]) => {
+          const flattenNsClaims = Object.entries(nsClaims).reduce(
+            (ac, [, el]) => ({
+              ...ac,
+              [el.elementIdentifier]: el.elementValue,
+            }),
+            {} as Record<string, unknown>
+          );
+
+          return {
+            ...acc,
+            [ns]: flattenNsClaims,
+          };
+        },
+        {} as DcqlMdocCredential["namespaces"]
+      );
+
+      return {
+        credential_format: "mso_mdoc",
+        doctype: issuerSigned.issuerAuth.payload.docType || "missing_doctype",
+        cryptographic_holder_binding: true,
+        namespaces,
+        original_credential: credential,
+      } satisfies CustomDcqlMdocCredential;
+    })
+  );
+};
+
+/**
+ * Extract a compact list of claims from the `dcql` result.
+ * @param match The DCQL query match
+ * @returns The list of claims in {@link EvaluatedDisclosure} format
+ */
+export const getClaimsFromDcqlMatch = (
+  match: DcqlQueryResult.CredentialMatch
+): EvaluatedDisclosure[] =>
+  getValidDcqlClaims(match).flatMap(({ output }) =>
+    Object.entries(output).flatMap(([ns, nsClaims]) =>
+      Object.keys(nsClaims).map((claimName) => ({
+        namespace: ns,
+        name: claimName,
+        value: nsClaims[claimName],
+      }))
+    )
+  );
+
+/**
+ * Build a presentation frame from the requested claims for selective disclosure.
+ * @param requestedClaims Claims in {@link EvaluatedDisclosure} format
+ * @param docType mdoc doctype
+ * @returns A presentation frame for ISO18013
+ * @example { "org.iso.18013.5.1.mDL": { "org.iso.18013.5.1": { first_name: true } } }
+ */
+export const getPresentationFrameFromClaims = (
+  requestedClaims: EvaluatedDisclosure[],
+  docType: string
+): PresentationFrame => ({
+  [docType]: requestedClaims.reduce((acc, { name, namespace }) => {
+    if (namespace) {
+      acc[namespace] ??= {};
+      const existingNamespace = acc[namespace] as Record<string, boolean>;
+      existingNamespace[name] = true;
+    } else {
+      acc[name] = true;
+    }
+    return acc;
+  }, {} as PresentationFrame),
+});

package/src/credential/status/README.md

@@ -1,22 +1,40 @@
-# Credential Status Assertion
+# Credential Status
 
-This flow is used to obtain a credential status assertion from its credential issuer. Each step in the flow is imported from the related file which is named with a sequential number.
+This flow is used to obtain the credential status from its credential issuer. The following methods are currently supported:
+- Status Assertion (v1.0.0)
+- Token Status List (v1.3.3)
+
+Each step in the flow is imported from the related file which is named with a sequential number.
+
+#### Status assertion
 The credential status assertion is a JWT which contains the credential status which indicates if the credential is valid or not (see [OAuth Status Assertions](https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/credential-revocation.html#oauth-status-assertions)).
 The status assertion is supposed to be stored securely along with the credential. It has a limited lifetime and should be refreshed periodically according to the `exp` field in the JWT payload.
 
+#### Status list
+The status list is a byte array embedded in a JWT/CWT, where a sequence of bits is used to represent the status of a digital credential. Each credential references the status list it is part of and the index to access its status. The following is an example for a SD-JWT credential:
+```json
+{
+  "status": {
+    "status_list": {
+      "idx": 1000,
+      "uri": "https://status-list.issuer.example"
+    }
+  }
+}
+```
+
 ## Sequence Diagram
 
 ```mermaid
 graph TD;
-    0[startFlow]
-    1[statusAssertion]
-    2[verifyAndParseStatusAssertion]
-
-    0 --> 1
-    1 --> 2
+  0[getStatusAssertion]
+  1[verifyAndParseStatusAssertion]
+  2[getStatusList]
+  3[verifyAndParseStatusList]
+  0 --> 1
+  2 --> 3
 ```
 
-
 ## Mapped results
 
 The following errors are mapped to a `IssuerResponseError` with specific codes.
@@ -27,23 +45,30 @@ The following errors are mapped to a `IssuerResponseError` with specific codes.
 
 ## Example
 
+The status assertion and list APIs are exposed under the namespaces `statusAssertion` and `statusList` respectively, and before using them it necessary to ensure they are supported:
+```ts
+if (CredentialStatus.statusAssertion.isSupported) {
+  // Safely invoke status assertion APIs...
+}
+if (CredentialStatus.statusList.isSupported) {
+  // Safely invoke status list APIs...
+}
+```
+
 <details>
   <summary>Credential status assertion flow</summary>
 
 ```ts
-// Start the issuance flow
-const credentialIssuerUrl = "https://issuer.example.com";
-const startFlow: Credential.Status.StartFlow = () => ({
-  issuerUrl: credentialIssuerUrl, // Let's assum
-});
+import { IoWallet } from "@pagopa/io-react-native-wallet";
 
-const { issuerUrl } = startFlow();
+const wallet = new IoWallet({ version: "1.0.0" });
+
+const credentialIssuerUrl = "https://issuer.example.com";
 
-// Evaluate issuer trust
-const { issuerConf } = await Credential.Status.evaluateIssuerTrust(issuerUrl);
+const { issuerConf } = await wallet.CredentialIssuance.evaluateIssuerTrust(credentialIssuerUrl);
 
 // Get the credential assertion
-const res = await Credential.Status.statusAssertion(
+const res = await wallet.CredentialStatus.statusAssertion.get(
   issuerConf,
   credential,
   format,
@@ -52,7 +77,7 @@ const res = await Credential.Status.statusAssertion(
 
 // Verify and parse the status assertion
 const { parsedStatusAssertion } =
-  await Credential.Status.verifyAndParseStatusAssertion(
+  await wallet.CredentialStatus.statusAssertion.verifyAndParse(
     issuerConf,
     res.statusAssertion,
     credential,
@@ -66,3 +91,36 @@ return {
 ```
 
 </details>
+
+<details>
+  <summary>Credential status list flow</summary>
+
+```ts
+import { IoWallet } from "@pagopa/io-react-native-wallet";
+
+const wallet = new IoWallet({ version: "1.3.3" });
+
+const credentialIssuerUrl = "https://issuer.example.com";
+
+const { issuerConf } = await wallet.CredentialIssuance.evaluateIssuerTrust(credentialIssuerUrl);
+
+// Get the status list
+const res = await wallet.CredentialStatus.statusList.get(
+  credential,
+  format,
+);
+
+// Verify and parse the status list response to get the credential status
+const { status } =
+  await wallet.CredentialStatus.statusList.verifyAndParse(
+    issuerConf,
+    res
+  );
+
+return {
+  statusList: res.statusList,
+  status,
+};
+```
+
+</details>

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

@@ -0,0 +1,23 @@
+import type { StatusAssertionApi } from "./status-assertion";
+import type { StatusListApi } from "./status-list";
+
+interface UnsupportedApi {
+  isSupported: false;
+}
+
+/**
+ * Credential status API. It supports status assertion and status list.
+ *
+ * **Important:** before using one or the other, ensure it is supported by the selected IT-Wallet version.
+ *
+ * @example
+ * if (CredentialStatus.statusList.isSupported) {
+ *   const statusList = await CredentialStatus.statusList.get(credential, format)
+ * }
+ */
+export interface CredentialStatusApi {
+  statusAssertion: StatusAssertionApi | UnsupportedApi;
+  statusList: StatusListApi | UnsupportedApi;
+}
+
+export * from "./types";

package/src/credential/status/api/status-assertion.ts

@@ -0,0 +1,57 @@
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
+import type { CredentialFormat, IssuerConfig } from "../../issuance/api";
+import type { SupportedSdJwtLegacyFormat } from "../../../sd-jwt/types";
+import type { Out } from "../../../utils/misc";
+import type { ParsedStatusAssertion } from "./types";
+
+export interface StatusAssertionApi {
+  isSupported: true;
+
+  /**
+   * Get the status assertion of a digital credential.
+   * @since 1.0.0
+   * @deprecated since 1.3.3 - Use `statusList.get`
+   *
+   * @param issuerConf - The issuer's configuration
+   * @param credential - The credential to be verified
+   * @param format - The format of the credential, e.g. "sd-jwt"
+   * @param context.credentialCryptoContext - The credential's crypto context
+   * @param context.wiaCryptoContext - The Wallet Attestation's crypto context
+   * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
+   * @returns The credential status assertion
+   * @throws {IssuerResponseError} with a specific code for more context
+   */
+  get(
+    issuerConf: IssuerConfig,
+    credential: string,
+    format: CredentialFormat | SupportedSdJwtLegacyFormat,
+    context: {
+      credentialCryptoContext: CryptoContext;
+      wiaCryptoContext: CryptoContext;
+      appFetch?: GlobalFetch["fetch"];
+    }
+  ): Promise<{ statusAssertion: string }>;
+
+  /**
+   * Given a status assertion, verifies that:
+   * - It's in the supported format;
+   * - The assertion is correctly signed;
+   * - It's bound to the given key.
+   * @since 1.0.0
+   * @deprecated since 1.3.3 - Use `statusList.verifyAndParse`
+   *
+   * @param issuerConf The Issuer configuration returned by `evaluateIssuerTrust`
+   * @param statusAssertion The encoded status assertion returned by `statusAssertion.get`
+   * @param credential The encoded credential whose status is being verified
+   * @param format The credential format, e.g. "dc+sd-jwt"
+   * @returns A parsed status assertion
+   * @throws {IoWalletError} If the credential signature is not verified with the Issuer key set
+   * @throws {IssuerResponseError} If the status assertion contains an error or the credential status is invalid
+   */
+  verifyAndParse(
+    issuerConf: IssuerConfig,
+    statusAssertion: Out<StatusAssertionApi["get"]>,
+    credential: string,
+    format: CredentialFormat | SupportedSdJwtLegacyFormat
+  ): Promise<{ parsedStatusAssertion: ParsedStatusAssertion }>;
+}

package/src/credential/status/api/status-list.ts

@@ -0,0 +1,50 @@
+import type { Out } from "../../../utils/misc";
+import type {
+  CredentialFormat,
+  IssuerConfig,
+} from "../../../credential/issuance/api";
+
+export interface StatusListApi {
+  isSupported: true;
+
+  /**
+   * Get the status list from the credential. This function fetches the list
+   * from the uri found in the credential's `status` claim.
+   * @example
+   * {
+   *   "status": {
+   *     "status_list": {
+   *       "idx": 1,
+   *       "uri": "https://example/status-list"
+   *     }
+   *   }
+   * }
+   * @since 1.3.3
+   * @param credential The credential to get the status list for
+   * @param format The credential format
+   * @returns The raw status list, the index of the credential and other metadata
+   */
+  get(
+    credential: string,
+    format: CredentialFormat,
+    context?: {
+      appFetch?: GlobalFetch["fetch"];
+    }
+  ): Promise<{
+    statusList: string;
+    format: "jwt";
+    uri: string;
+    idx: number;
+  }>;
+
+  /**
+   * Verifies the signature of a status list and extract the status at the specified index.
+   * @since 1.3.3
+   * @param issuerConf The Credential Issuer common configuration
+   * @param statusListParams The raw status list, the index to read and other metadata
+   */
+  verifyAndParse(
+    issuerConf: IssuerConfig,
+    statusListParams: Out<StatusListApi["get"]>
+  ): Promise<{ status: number }>;
+}