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

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

@@ -0,0 +1,90 @@
+import { UnixTime } from "../../../utils/zod";
+import { JWK } from "../../../utils/jwk";
+import * as z from "zod";
+
+/**
+ * Shape from parsing a status assertion response in case of 201.
+ */
+export const StatusAssertionResponse = z.object({
+  status_assertion_responses: z.array(z.string()),
+});
+
+/**
+ * Type from parsing a status assertion response in case of 201.
+ * Inferred from {@link StatusAssertionResponse}.
+ */
+export type StatusAssertionResponse = z.infer<typeof StatusAssertionResponse>;
+
+export type ParsedStatusAssertionJwt = z.infer<typeof ParsedStatusAssertionJwt>;
+
+/**
+ * Shape for parsing a successful status assertion in a JWT.
+ */
+export const ParsedStatusAssertionJwt = z.object({
+  header: z.object({
+    typ: z.literal("status-assertion+jwt"),
+    alg: z.string(),
+    kid: z.string().optional(),
+  }),
+  payload: z.object({
+    iss: z.string(),
+    credential_status_type: z.string(),
+    credential_status_detail: z
+      .object({
+        state: z.string(),
+        description: z.string(),
+      })
+      .optional(),
+    credential_hash_alg: z.string(),
+    credential_hash: z.string(),
+    cnf: z.object({
+      jwk: JWK,
+    }),
+    exp: UnixTime,
+    iat: UnixTime,
+  }),
+});
+
+export type ParsedStatusAssertionErrorJwt = z.infer<
+  typeof ParsedStatusAssertionErrorJwt
+>;
+
+/**
+ * The JWT that contains the errors occurred for the status assertion request.
+ * @see https://italia.github.io/eid-wallet-it-docs/releases/1.0.1/en/credential-revocation.html#http-status-assertion-response
+ */
+export const ParsedStatusAssertionErrorJwt = z.object({
+  header: z.object({
+    typ: z.literal("status-assertion-error+jwt"),
+    alg: z.string(),
+    kid: z.string().optional(),
+  }),
+  payload: z.object({
+    credential_hash_alg: z.string(),
+    credential_hash: z.string(),
+    error: z.string(),
+    error_description: z.string(),
+  }),
+});
+
+/**
+ * The status assertion response that might include either a successful assertion or an error
+ */
+export type ParsedStatusAssertionResponse = z.infer<
+  typeof ParsedStatusAssertionResponse
+>;
+export const ParsedStatusAssertionResponse = z.union([
+  ParsedStatusAssertionJwt,
+  ParsedStatusAssertionErrorJwt,
+]);
+
+export enum StatusType {
+  VALID = "0x00",
+  INVALID = "0x01",
+  SUSPENDED = "0x02",
+}
+
+export type InvalidStatusErrorReason = {
+  error: string;
+  error_description: string;
+};

package/src/credential/status/v1.3.3/01-status-list.ts

@@ -0,0 +1,50 @@
+import { CBOR } from "@pagopa/io-react-native-iso18013";
+import {
+  getStatusListFromJWT,
+  type StatusListEntry,
+} from "@sd-jwt/jwt-status-list";
+import { IoWalletError } from "../../../utils/errors";
+import { hasStatusOrThrow } from "../../../utils/misc";
+import type { CredentialFormat } from "../../../credential/issuance/api";
+import type { StatusListApi } from "../api/status-list";
+
+const getStatusListEntry = async (
+  credential: string,
+  format: CredentialFormat
+): Promise<StatusListEntry> => {
+  let statusListEntry: StatusListEntry | undefined;
+
+  if (format === "mso_mdoc") {
+    // TODO: improve typing
+    const decoded = await CBOR.decode(credential);
+    statusListEntry = decoded.issuerAuth?.payload?.status?.status_list;
+  }
+
+  if (format === "dc+sd-jwt") {
+    statusListEntry = getStatusListFromJWT(credential);
+  }
+
+  if (!statusListEntry) {
+    throw new IoWalletError("Status list reference not found in credential");
+  }
+
+  return statusListEntry;
+};
+
+export const getStatusList: StatusListApi["get"] = async (
+  credential,
+  format,
+  { appFetch = fetch } = {}
+) => {
+  const { uri, idx } = await getStatusListEntry(credential, format);
+
+  const statusList = await appFetch(uri, {
+    headers: {
+      Accept: "application/statuslist+jwt",
+    },
+  })
+    .then(hasStatusOrThrow(200))
+    .then((response) => response.text());
+
+  return { statusList, uri, idx, format: "jwt" };
+};

package/src/credential/status/v1.3.3/02-verify-and-parse-status-list.ts

@@ -0,0 +1,19 @@
+import { verify } from "@pagopa/io-react-native-jwt";
+import { getListFromStatusListJWT } from "@sd-jwt/jwt-status-list";
+import type { StatusListApi } from "../api/status-list";
+
+export const verifyAndParseStatusList: StatusListApi["verifyAndParse"] = async (
+  issuerConf,
+  { statusList: rawStatusList, idx }
+) => {
+  await verify(rawStatusList, issuerConf.keys);
+
+  const statusList = getListFromStatusListJWT(rawStatusList);
+
+  const status = statusList.getStatus(idx);
+
+  // TODO: [SIW-3992] Improve the return object with additional data, throw CredentialInvalidStatus when invalid
+  return {
+    status,
+  };
+};

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

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

package/src/credential/trustmark/README.md

@@ -42,6 +42,10 @@ Returns a Promise that resolves to an object containing:
 ## Example
 
 ```typescript
+import { IoWallet } from "@pagopa/io-react-native-wallet";
+
+const wallet = new IoWallet({ version: "1.0.0" });
+
 // Required inputs
 const walletInstanceAttestation = "base64AttestationString";
 const credentialType = "MDL"; // Credential type (e.g., Mobile Driver's License)
@@ -49,7 +53,7 @@ const documentNumber = "AB123456"; // Optional document number
 const cryptoContext = createCryptoContextFor("wiaKeyTag"); // Sample crypto context
 
 // Generate the TrustMark JWT
-const { jwt, expirationTime } = await getCredentialTrustmark({
+const { jwt, expirationTime } = await wallet.Trustmark.getCredentialTrustmark({
   walletInstanceAttestation: "eyJ0eXAi...", // WIA JWT
   wiaCryptoContext: cryptoContext,
   credentialType: "IdentityCard",

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

@@ -0,0 +1,50 @@
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
+
+export type GetCredentialTrustmarkJwt = (params: {
+  /**
+   * The Wallet Instance's attestation
+   */
+  walletInstanceAttestation: string;
+  /**
+   * The Wallet Instance's crypto context associated with the walletInstanceAttestation parameter
+   */
+  wiaCryptoContext: CryptoContext;
+  /**
+   * The type of credential for which the trustmark is generated
+   */
+  credentialType: string;
+  /**
+   * (Optional) Document number contained in the credential, if applicable
+   */
+  docNumber?: string;
+  /**
+   * (Optional) Expiration time for the trustmark, default is 2 minutes.
+   * If a number is provided, it is interpreted as a timestamp in seconds.
+   * If a string is provided, it is interpreted as a time span and added to the current timestamp.
+   */
+  expirationTime?: number | string;
+}) => Promise<{
+  /**
+   * The signed JWT
+   */
+  jwt: string;
+  /**
+   * The expiration time of the JWT in seconds
+   */
+  expirationTime: number;
+}>;
+
+export interface TrustmarkApi {
+  /**
+   * Generates a trustmark signed JWT, which is used to verify the authenticity of a credential.
+   * The public key used to sign the trustmark must the same used for the Wallet Instance Attestation.
+   *
+   * @since 1.0.0
+   *
+   * @throws {IoWalletError} If the WIA is expired
+   * @throws {IoWalletError} If the public key associated to the WIA is not the same for the CryptoContext
+   * @throws {JWSSignatureVerificationFailed} If the WIA signature is not valid
+   * @returns A promise containing the signed JWT and its expiration time in seconds
+   */
+  getCredentialTrustmark: GetCredentialTrustmarkJwt;
+}

package/src/credential/trustmark/index.ts

@@ -1,8 +1,3 @@
-import {
-  type GetCredentialTrustmarkJwt,
-  getCredentialTrustmark,
-} from "./get-credential-trustmark";
-
-export { getCredentialTrustmark };
-
-export type { GetCredentialTrustmarkJwt };
+export type * from "./api";
+export { Trustmark as V1_0_0 } from "./v1.0.0";
+export { Trustmark as V1_3_3 } from "./v1.3.3";

package/src/credential/trustmark/v1.0.0/get-credential-trustmark.ts

@@ -0,0 +1,89 @@
+import {
+  SignJWT,
+  thumbprint,
+  decode as decodeJwt,
+} from "@pagopa/io-react-native-jwt";
+import { type TrustmarkApi as Api } from "../api";
+import * as WalletInstanceAttestation from "../../../wallet-instance-attestation/v1.0.0/utils";
+import { IoWalletError } from "../../../utils/errors";
+import { obfuscateString } from "../../../utils/string";
+import { LogLevel, Logger } from "../../../utils/logging";
+
+export const getCredentialTrustmark: Api["getCredentialTrustmark"] = async ({
+  walletInstanceAttestation,
+  wiaCryptoContext,
+  credentialType,
+  docNumber,
+  expirationTime = "2m",
+}) => {
+  /**
+   * Check that the public key used to sign the trustmark is the one used for the WIA
+   */
+  const holderBindingKey = await wiaCryptoContext.getPublicKey();
+  const decodedWia = WalletInstanceAttestation.decode(
+    walletInstanceAttestation
+  );
+
+  Logger.log(
+    LogLevel.DEBUG,
+    `Decoded wia ${JSON.stringify(decodedWia.payload)} with holder binding key ${JSON.stringify(holderBindingKey)}`
+  );
+
+  /**
+   * Check that the WIA is not expired
+   */
+  if (decodedWia.payload.exp * 1000 < Date.now()) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Wallet Instance Attestation expired with exp: ${decodedWia.payload.exp}`
+    );
+    throw new IoWalletError("Wallet Instance Attestation expired");
+  }
+
+  /**
+   * Verify holder binding by comparing thumbprints of the WIA and the CryptoContext key
+   */
+  const wiaThumbprint = await thumbprint(decodedWia.payload.cnf.jwk);
+  const cryptoContextThumbprint = await thumbprint(holderBindingKey);
+
+  if (wiaThumbprint !== cryptoContextThumbprint) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Failed to verify holder binding for status attestation, expected thumbprint: ${cryptoContextThumbprint}, got: ${wiaThumbprint}`
+    );
+    throw new IoWalletError(
+      `Failed to verify holder binding for status attestation, expected thumbprint: ${cryptoContextThumbprint}, got: ${wiaThumbprint}`
+    );
+  }
+
+  Logger.log(
+    LogLevel.DEBUG,
+    `Wia thumbprint: ${wiaThumbprint} CryptoContext thumbprint: ${cryptoContextThumbprint}`
+  );
+
+  /**
+   * Generate Trustmark signed JWT
+   */
+  const signedTrustmarkJwt = await new SignJWT(wiaCryptoContext)
+    .setProtectedHeader({
+      alg: "ES256",
+    })
+    .setPayload({
+      iss: walletInstanceAttestation,
+      /**
+       * If present, the document number is obfuscated before adding it to the payload
+       */
+      ...(docNumber ? { sub: obfuscateString(docNumber) } : {}),
+      subtyp: credentialType,
+    })
+    .setIssuedAt()
+    .setExpirationTime(expirationTime)
+    .sign();
+
+  const decodedTrustmark = decodeJwt(signedTrustmarkJwt);
+
+  return {
+    jwt: signedTrustmarkJwt,
+    expirationTime: decodedTrustmark.payload.exp ?? 0,
+  };
+};

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

@@ -0,0 +1,6 @@
+import { getCredentialTrustmark } from "./get-credential-trustmark";
+import type { TrustmarkApi } from "../api";
+
+export const Trustmark: TrustmarkApi = {
+  getCredentialTrustmark,
+};

package/src/credential/trustmark/v1.3.3/get-credential-trustmark.ts

@@ -0,0 +1,7 @@
+import { UnimplementedFeatureError } from "../../../utils/errors";
+import { type TrustmarkApi as Api } from "../api";
+
+export const getCredentialTrustmark: Api["getCredentialTrustmark"] =
+  async () => {
+    throw new UnimplementedFeatureError("getCredentialTrustmark", "1.3.3");
+  };

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

@@ -0,0 +1,6 @@
+import { getCredentialTrustmark } from "./get-credential-trustmark";
+import type { TrustmarkApi } from "../api";
+
+export const Trustmark: TrustmarkApi = {
+  getCredentialTrustmark,
+};

package/src/credentials-catalogue/README.md

@@ -8,8 +8,14 @@ The module allows:
 ## Usage
 
 ```ts
-// Fetch the catalogue
+import { IoWallet } from "@pagopa/io-react-native-wallet";
+
 const TRUST_ANCHOR_BASE_URL = "https://pre.ta.wallet.ipzs.it";
+
+// Instantiate the SDK with a specific version
+const wallet = new IoWallet({ version: "1.0.0" });
+
+// Fetch the catalogue
 const credentialsCatalogue =
-  await CredentialsCatalogue.fetchAndParseCatalogue(TRUST_ANCHOR_BASE_URL);
+  await wallet.CredentialsCatalogue.fetchAndParseCatalogue(TRUST_ANCHOR_BASE_URL);
 ```

package/src/credentials-catalogue/api/DigitalCredentialsCatalogue.ts

@@ -0,0 +1,82 @@
+import * as z from "zod";
+import { UnixTime } from "../../utils/zod";
+
+const CredentialPurpose = z.object({
+  id: z.string(),
+  description: z.string(),
+  claims_required: z.array(z.string()),
+  claim_recommended: z.array(z.string()),
+});
+
+const CredentialIssuer = z.object({
+  id: z.string(),
+  organization_name: z.string(),
+  organization_code: z.string(),
+  organization_country: z.string(),
+  contacts: z.array(z.string()).optional(),
+  homepage_uri: z.string().optional(),
+  logo_uri: z.string().optional(),
+  policy_uri: z.string().optional(),
+  tos_uri: z.string().optional(),
+});
+
+const AuthenticSource = z.object({
+  id: z.string(),
+  organization_name: z.string(),
+  organization_code: z.string().optional(),
+  organization_country: z.string(),
+  organization_type: z.string(),
+  contacts: z.array(z.string()).optional(),
+  homepage_uri: z.string().optional(),
+  logo_uri: z.string().optional(),
+  user_information: z.string().optional(),
+});
+export type AuthenticSource = z.infer<typeof AuthenticSource>;
+
+export const CredentialFormat = z.object({
+  configuration_id: z.string(),
+  format: z.enum(["dc+sd-jwt", "mso_mdoc"]),
+  vct: z.string().url().optional(),
+  docType: z.string().optional(),
+  schema_uri: z.string().url().optional(),
+  "schema_uri#integrity": z.string().optional(),
+});
+export type CredentialFormat = z.infer<typeof CredentialFormat>;
+
+export const Claim = z.object({
+  name: z.string(),
+  taxonomy_ref: z.string(),
+  display_name: z.string(),
+});
+
+/**
+ * Unified shape for a Digital Credential in the catalogue, regardless of IT-Wallet version.
+ * Please note that some of the version-specific properties might be missing in this representation.
+ */
+export const DigitalCredential = z.object({
+  version: z.string(),
+  credential_type: z.string(),
+  legal_type: z.string(),
+  name: z.string(),
+  description: z.string(),
+  validity_info: z.object({
+    max_validity_days: z.number(),
+    status_methods: z.array(z.string()),
+    allowed_states: z.array(z.string()),
+  }),
+  purposes: z.array(CredentialPurpose),
+  issuers: z.array(CredentialIssuer),
+  authentic_sources: z.array(AuthenticSource),
+  formats: z.array(CredentialFormat),
+  // claims: z.array(Claim), // TODO: [SIW-3978] Should we keep claims?
+});
+
+export const DigitalCredentialsCatalogue = z.object({
+  taxonomy_uri: z.string().url(),
+  credentials: z.array(DigitalCredential),
+  iat: UnixTime,
+  exp: UnixTime,
+});
+export type DigitalCredentialsCatalogue = z.infer<
+  typeof DigitalCredentialsCatalogue
+>;

package/src/credentials-catalogue/api/index.ts

@@ -0,0 +1,21 @@
+import { type DigitalCredentialsCatalogue } from "./DigitalCredentialsCatalogue";
+
+type FetchContext = { appFetch?: GlobalFetch["fetch"] };
+
+export interface CredentialsCatalogueApi {
+  /**
+   * Fetch and parse the Digital Credential Catalogue from the Trust Anchor.
+   * The catalogue's JWT signature is verified against the Trust Anchor's JWKs.
+   *
+   * @since 1.0.0
+   * @param trustAnchorBaseUrl Base URL of the Trust Anchor
+   * @param context.appFetch (optional) fetch API implementation. Default: built-in fetch
+   * @returns The Digital Credential Catalogue payload
+   */
+  fetchAndParseCatalogue(
+    trustAnchorBaseUrl: string,
+    ctx?: FetchContext
+  ): Promise<DigitalCredentialsCatalogue>;
+}
+
+export { type DigitalCredentialsCatalogue };

package/src/credentials-catalogue/index.ts

@@ -1,2 +1,3 @@
-export { fetchAndParseCatalogue } from "./fetch-and-parse-catalogue";
-export { type DigitalCredentialsCatalogue } from "./types";
+export type * from "./api";
+export { CredentialsCatalogue as V1_0_0 } from "./v1.0.0";
+export { CredentialsCatalogue as V1_3_3 } from "./v1.3.3";

package/src/credentials-catalogue/v1.0.0/fetch-and-parse-catalogue.ts

@@ -0,0 +1,41 @@
+import { decode as decodeJwt, verify } from "@pagopa/io-react-native-jwt";
+import { hasStatusOrThrow } from "../../utils/misc";
+import { IoWalletError } from "../../utils/errors";
+import { getTrustAnchorEntityConfiguration } from "../../trust/v1.0.0/entities";
+import { type CredentialsCatalogueApi as Api } from "../api";
+import { mapToCredentialsCatalogue } from "./mappers";
+
+export const fetchAndParseCatalogue: Api["fetchAndParseCatalogue"] = async (
+  trustAnchorBaseUrl,
+  { appFetch = fetch } = {}
+) => {
+  const trustAnchorConfig =
+    await getTrustAnchorEntityConfiguration(trustAnchorBaseUrl);
+
+  const responseText = await appFetch(
+    `${trustAnchorConfig.payload.sub}/.well-known/credential-catalogue`,
+    { method: "GET" }
+  )
+    .then(hasStatusOrThrow(200))
+    .then((res) => res.text());
+
+  const responseJwt = decodeJwt(responseText);
+  const catalogueKid = responseJwt.protectedHeader.kid;
+
+  const trustAnchorJwk = trustAnchorConfig.payload.jwks.keys.find(
+    (jwk) => jwk.kid === catalogueKid
+  );
+
+  if (!trustAnchorJwk) {
+    throw new IoWalletError(
+      `Could not find JWK with kid ${catalogueKid} in Trust Anchor's Entity Configuration`
+    );
+  }
+
+  await verify(responseText, trustAnchorJwk);
+
+  return mapToCredentialsCatalogue({
+    header: responseJwt.protectedHeader,
+    payload: responseJwt.payload,
+  });
+};

package/src/credentials-catalogue/v1.0.0/index.ts

@@ -0,0 +1,6 @@
+import type { CredentialsCatalogueApi } from "../api";
+import { fetchAndParseCatalogue } from "./fetch-and-parse-catalogue";
+
+export const CredentialsCatalogue: CredentialsCatalogueApi = {
+  fetchAndParseCatalogue,
+};

package/src/credentials-catalogue/v1.0.0/mappers.ts

@@ -0,0 +1,20 @@
+import { createMapper } from "../../utils/mappers";
+import { DigitalCredentialsCatalogue } from "../api/DigitalCredentialsCatalogue";
+import { DigitalCredentialsCatalogueJwt } from "./types";
+
+export const mapToCredentialsCatalogue = createMapper(
+  ({ payload }) => ({
+    ...payload,
+    credentials: payload.credentials.map((credential) => ({
+      ...credential,
+      authentic_sources: credential.authentic_sources.map((as) => ({
+        ...as,
+        organization_type: as.source_type,
+      })),
+    })),
+  }),
+  {
+    inputSchema: DigitalCredentialsCatalogueJwt,
+    outputSchema: DigitalCredentialsCatalogue,
+  }
+);

package/src/credentials-catalogue/v1.0.0/types.ts

@@ -0,0 +1,97 @@
+import * as z from "zod";
+import { UnixTime } from "../../utils/zod";
+
+const CredentialPurpose = z.object({
+  id: z.string(),
+  description: z.string(),
+  category: z.string().optional(),
+  subcategory: z.string().optional(),
+  claims_required: z.array(z.string()),
+  claim_recommended: z.array(z.string()),
+});
+
+const CredentialIssuer = z.object({
+  id: z.string(),
+  organization_name: z.string(),
+  organization_code: z.string(),
+  organization_country: z.string(),
+  contacts: z.array(z.string()).optional(),
+  homepage_uri: z.string().optional(),
+  logo_uri: z.string().optional(),
+  policy_uri: z.string().optional(),
+  tos_uri: z.string().optional(),
+});
+
+const AuthenticSource = z.object({
+  id: z.string(),
+  organization_name: z.string(),
+  organization_code: z.string(),
+  organization_country: z.string(),
+  source_type: z.string(),
+  contacts: z.array(z.string()).optional(),
+  homepage_uri: z.string().optional(),
+  logo_uri: z.string().optional(),
+  user_information: z.string().optional(),
+});
+
+const CredentialFormat = z.object({
+  configuration_id: z.string(),
+  format: z.enum(["dc+sd-jwt", "mso_mdoc"]),
+  vct: z.string().url().optional(),
+  docType: z.string().optional(),
+  schema_uri: z.string().url().optional(),
+  "schema_uri#integrity": z.string().optional(),
+});
+
+const Claim = z.object({
+  name: z.string(),
+  taxonomy_ref: z.string(),
+  display_name: z.string(),
+});
+
+export const DigitalCredential = z.object({
+  version: z.string(),
+  credential_type: z.string(),
+  legal_type: z.string(),
+  name: z.string(),
+  description: z.string(),
+  validity_info: z.object({
+    max_validity_days: z.number(),
+    status_methods: z.array(z.string()),
+    allowed_states: z.array(z.string()),
+  }),
+  authentication: z.object({
+    user_auth_required: z.boolean(),
+    min_loa: z.string(),
+    supported_eid_schemes: z.array(z.string()),
+  }),
+  purposes: z.array(CredentialPurpose),
+  issuers: z.array(CredentialIssuer),
+  authentic_sources: z.array(AuthenticSource),
+  formats: z.array(CredentialFormat),
+  claims: z.array(Claim),
+});
+
+/**
+ * The Digital Credentials Catalogue published by the Trust Anchor
+ *
+ * @version 1.1.0
+ * @see https://italia.github.io/eid-wallet-it-docs/releases/1.1.0/en/registry-catalogue.html
+ */
+export const DigitalCredentialsCatalogueJwt = z.object({
+  header: z.object({
+    typ: z.string(),
+    alg: z.string(),
+    kid: z.string(),
+  }),
+  payload: z.object({
+    catalog_version: z.string(),
+    taxonomy_uri: z.string().url(),
+    credentials: z.array(DigitalCredential),
+    iat: UnixTime,
+    exp: UnixTime,
+  }),
+});
+export type DigitalCredentialsCatalogueJwt = z.infer<
+  typeof DigitalCredentialsCatalogueJwt
+>;