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

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 }>;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Common type for a parsed Status Assertion
+ */
+export type ParsedStatusAssertion = {
+  iss: string;
+  iat: number;
+  exp: number;
+  credential_hash: string;
+  credential_hash_alg: string;
+  credential_status_type: string;
+  credential_status_detail?: {
+    state: string;
+    description: string;
+  };
+};

package/src/credential/status/index.ts

@@ -1,15 +1,3 @@
-import { type StartFlow } from "./01-start-flow";
-import { statusAssertion, type StatusAssertion } from "./02-status-assertion";
-import { evaluateIssuerTrust, type EvaluateIssuerTrust } from "../issuance";
-import {
-  verifyAndParseStatusAssertion,
-  type VerifyAndParseStatusAssertion,
-} from "./03-verify-and-parse-status-assertion";
-
-export { evaluateIssuerTrust, statusAssertion, verifyAndParseStatusAssertion };
-export type {
-  StartFlow,
-  EvaluateIssuerTrust,
-  StatusAssertion,
-  VerifyAndParseStatusAssertion,
-};
+export * from "./api";
+export { CredentialStatus as V1_0_0 } from "./v1.0.0";
+export { CredentialStatus as V1_3_3 } from "./v1.3.3";

package/src/credential/status/v1.0.0/01-status-assertion.ts

@@ -0,0 +1,95 @@
+import {
+  getCredentialHashWithouDiscloures,
+  hasStatusOrThrow,
+} from "../../../utils/misc";
+import { SignJWT } from "@pagopa/io-react-native-jwt";
+import { v4 as uuidv4 } from "uuid";
+import { StatusAssertionResponse } from "./types";
+import {
+  IoWalletError,
+  IssuerResponseError,
+  IssuerResponseErrorCodes,
+  ResponseErrorBuilder,
+  UnexpectedStatusCodeError,
+} from "../../../utils/errors";
+import { Logger, LogLevel } from "../../../utils/logging";
+import { extractJwkFromCredential } from "../../../utils/credentials";
+import type { StatusAssertionApi } from "../api/status-assertion";
+
+export const getStatusAssertion: StatusAssertionApi["get"] = async (
+  issuerConf,
+  credential,
+  format,
+  ctx
+) => {
+  const { credentialCryptoContext, wiaCryptoContext, appFetch = fetch } = ctx;
+
+  const jwk = await extractJwkFromCredential(credential, format);
+  const issuerJwk = await wiaCryptoContext.getPublicKey();
+  const credentialHash = await getCredentialHashWithouDiscloures(credential);
+  const statusAttUrl = issuerConf.status_assertion_endpoint;
+
+  if (!statusAttUrl) {
+    throw new IoWalletError(
+      "Status assertion endpoint not found in the Issuer configuration"
+    );
+  }
+
+  const credentialPop = await new SignJWT(credentialCryptoContext)
+    .setPayload({
+      iss: issuerJwk.kid,
+      aud: statusAttUrl,
+      jti: uuidv4().toString(),
+      credential_hash: credentialHash,
+      credential_hash_alg: "sha-256",
+    })
+    .setProtectedHeader({
+      alg: "ES256",
+      typ: "status-assertion-request+jwt",
+      kid: jwk.kid,
+    })
+    .setIssuedAt()
+    .setExpirationTime("5m")
+    .sign();
+
+  const body = {
+    status_assertion_requests: [credentialPop],
+  };
+
+  Logger.log(LogLevel.DEBUG, `Credential pop: ${credentialPop}`);
+
+  const result = await appFetch(statusAttUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  })
+    .then(hasStatusOrThrow(200))
+    .then((raw) => raw.json())
+    .then((json) => StatusAssertionResponse.parse(json))
+    .catch(handleStatusAssertionError);
+
+  const [statusAttestationJwt] = result.status_assertion_responses;
+
+  return { statusAssertion: statusAttestationJwt! };
+};
+
+/**
+ * Handle the status assertion 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 {IssuerResponseError} with a specific code for more context
+ */
+const handleStatusAssertionError = (e: unknown) => {
+  if (!(e instanceof UnexpectedStatusCodeError)) {
+    throw e;
+  }
+
+  throw new ResponseErrorBuilder(IssuerResponseError)
+    .handle("*", {
+      code: IssuerResponseErrorCodes.StatusAttestationRequestFailed,
+      message: `Unable to obtain the status assertion for the given credential`,
+    })
+    .buildFrom(e);
+};

package/src/credential/status/v1.0.0/02-verify-and-parse-status-assertion.ts

@@ -0,0 +1,87 @@
+import {
+  IoWalletError,
+  IssuerResponseError,
+  IssuerResponseErrorCodes,
+} from "../../../utils/errors";
+import { decode as decodeJwt, verify } from "@pagopa/io-react-native-jwt";
+import {
+  type InvalidStatusErrorReason,
+  ParsedStatusAssertionErrorJwt,
+  ParsedStatusAssertionResponse,
+  StatusType,
+} from "./types";
+import { Logger, LogLevel } from "../../../utils/logging";
+import { extractJwkFromCredential } from "../../../utils/credentials";
+import { isSameThumbprint } from "../../../utils/jwk";
+import type { StatusAssertionApi } from "../api/status-assertion";
+import { mapToParsedStatusAssertion } from "./mappers";
+
+export const verifyAndParseStatusAssertion: StatusAssertionApi["verifyAndParse"] =
+  async (issuerConf, rawStatusAssertion, credential, format) => {
+    const { statusAssertion } = rawStatusAssertion;
+
+    await verify(statusAssertion, issuerConf.keys);
+
+    const decodedJwt = decodeJwt(statusAssertion);
+    const parsedStatusAssertion = ParsedStatusAssertionResponse.parse({
+      header: decodedJwt.protectedHeader,
+      payload: decodedJwt.payload,
+    });
+
+    Logger.log(
+      LogLevel.DEBUG,
+      `Parsed status assertion: ${JSON.stringify(parsedStatusAssertion)}`
+    );
+
+    // Errors are transmitted in the JWT and use a 200 HTTP status code
+    if (isStatusAssertionError(parsedStatusAssertion)) {
+      throw new IssuerResponseError({
+        code: IssuerResponseErrorCodes.CredentialInvalidStatus,
+        message: "The status assertion contains an error",
+        statusCode: 200,
+        reason: buildErrorReason(parsedStatusAssertion),
+      });
+    }
+
+    const { cnf, credential_status_type } = parsedStatusAssertion.payload;
+    const holderBindingKey = await extractJwkFromCredential(credential, format);
+
+    if (!(await isSameThumbprint(cnf.jwk, holderBindingKey))) {
+      const errorMessage = `Failed to verify holder binding for status assertion: the thumbprints of keys ${cnf.jwk.kid} and ${holderBindingKey.kid} do not match`;
+      Logger.log(LogLevel.ERROR, errorMessage);
+      throw new IoWalletError(errorMessage);
+    }
+
+    if (credential_status_type !== StatusType.VALID) {
+      throw new IssuerResponseError({
+        code: IssuerResponseErrorCodes.CredentialInvalidStatus,
+        message: "Invalid status found for the given credential",
+        statusCode: 200,
+        reason: buildErrorReason(parsedStatusAssertion),
+      });
+    }
+
+    return {
+      parsedStatusAssertion: mapToParsedStatusAssertion(parsedStatusAssertion),
+    };
+  };
+
+const isStatusAssertionError = (
+  assertion: ParsedStatusAssertionResponse
+): assertion is ParsedStatusAssertionErrorJwt =>
+  assertion.header.typ === "status-assertion-error+jwt";
+
+/**
+ * Build an object containing the details on the error to use as the IssuerResponseError's reason
+ * @param assertion The status assertion response, both success or failure
+ * @returns The error's reason object
+ */
+const buildErrorReason = ({
+  payload,
+}: ParsedStatusAssertionResponse): InvalidStatusErrorReason =>
+  "error" in payload
+    ? payload
+    : {
+        error: payload.credential_status_detail!.state,
+        error_description: payload.credential_status_detail!.description,
+      };

package/src/credential/status/v1.0.0/index.ts

@@ -0,0 +1,14 @@
+import type { CredentialStatusApi } from "../api";
+import { getStatusAssertion } from "./01-status-assertion";
+import { verifyAndParseStatusAssertion } from "./02-verify-and-parse-status-assertion";
+
+export const CredentialStatus: CredentialStatusApi = {
+  statusAssertion: {
+    isSupported: true,
+    get: getStatusAssertion,
+    verifyAndParse: verifyAndParseStatusAssertion,
+  },
+  statusList: {
+    isSupported: false,
+  },
+};

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

@@ -0,0 +1,8 @@
+import { createMapper } from "../../../utils/mappers";
+import type { ParsedStatusAssertion } from "../api/types";
+import type { ParsedStatusAssertionJwt } from "./types";
+
+export const mapToParsedStatusAssertion = createMapper<
+  ParsedStatusAssertionJwt,
+  ParsedStatusAssertion
+>((x) => x.payload);