@pagopa/io-react-native-wallet 2.1.1 → 2.3.0

package/src/credential/offer/errors.ts

@@ -0,0 +1,17 @@
+import { IoWalletError } from "../../utils/errors";
+
+export class InvalidCredentialOfferError extends IoWalletError {
+  code = "ERR_INVALID_CREDENTIAL_OFFER";
+
+  constructor(message?: string) {
+    super(message);
+  }
+}
+
+export class InvalidQRCodeError extends IoWalletError {
+  code = "ERR_INVALID_QR_CODE";
+
+  constructor(message?: string) {
+    super(message);
+  }
+}

package/src/credential/offer/index.ts

@@ -0,0 +1,16 @@
+import { startFlowFromQR, type StartFlow } from "./01-start-flow";
+import {
+  fetchCredentialOffer,
+  type GetCredentialOffer,
+} from "./02-fetch-credential-offer";
+import * as Errors from "./errors";
+export type {
+  CredentialOffer,
+  Grants,
+  AuthorizationCodeGrant,
+  PreAuthorizedCodeGrant,
+  TransactionCode,
+} from "./types";
+
+export { Errors, fetchCredentialOffer, startFlowFromQR };
+export type { GetCredentialOffer, StartFlow };

package/src/credential/offer/types.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+/**
+ * OAuth 2.0 Authorization Code flow parameters.
+ */
+export const AuthorizationCodeGrantSchema = z.object({
+  issuer_state: z.string().optional(),
+  authorization_server: z.string().url().optional(),
+});
+
+export type AuthorizationCodeGrant = z.infer<
+  typeof AuthorizationCodeGrantSchema
+>;
+
+/**
+ * Transaction Code requirements for Pre-Authorized Code flow.
+ */
+export const TransactionCodeSchema = z.object({
+  input_mode: z.enum(["numeric", "text"]).optional(),
+  length: z.number().int().positive().optional(),
+  description: z.string().max(300).optional(),
+});
+
+export type TransactionCode = z.infer<typeof TransactionCodeSchema>;
+
+/**
+ * Pre-Authorized Code flow parameters.
+ */
+export const PreAuthorizedCodeGrantSchema = z.object({
+  "pre-authorized_code": z.string(),
+  tx_code: TransactionCodeSchema.optional(),
+  authorization_server: z.string().url().optional(),
+});
+
+export type PreAuthorizedCodeGrant = z.infer<
+  typeof PreAuthorizedCodeGrantSchema
+>;
+
+/**
+ * Supported grant types for Credential Offer.
+ */
+export const GrantsSchema = z.object({
+  authorization_code: AuthorizationCodeGrantSchema.optional(),
+  "urn:ietf:params:oauth:grant-type:pre-authorized_code":
+    PreAuthorizedCodeGrantSchema.optional(),
+});
+
+export type Grants = z.infer<typeof GrantsSchema>;
+
+/**
+ * Credential Offer object as defined in OpenID4VCI Section 4.1.1.
+ */
+export const CredentialOfferSchema = z.object({
+  credential_issuer: z.string().url(),
+  credential_configuration_ids: z.array(z.string()).min(1),
+  grants: GrantsSchema.optional(),
+});
+
+export type CredentialOffer = z.infer<typeof CredentialOfferSchema>;

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

@@ -11,7 +11,7 @@ export type PresentationParams = z.infer<typeof PresentationParams>;
 
 /**
  * The beginning of the presentation flow.
- * To be implemented accordind to the user touchpoint
+ * To be implemented according to the user touchpoint
  *
  * @param params Presentation parameters, depending on the starting touchpoint
  * @returns The url for the Relying Party to connect with

package/src/credentials-catalogue/README.md

@@ -0,0 +1,15 @@
+# Digital Credentials Catalogue
+
+Module that manages the [**Digital Credentials Catalogue**](https://italia.github.io/eid-wallet-it-docs/releases/1.1.0/en/registry-catalogue.html) published by the Trust Anchor.
+
+The module allows:
+- Fetching, verifying and parsing the catalogue's JWT.
+
+## Usage
+
+```ts
+// Fetch the catalogue
+const TRUST_ANCHOR_BASE_URL = "https://pre.ta.wallet.ipzs.it";
+const credentialsCatalogue =
+  await CredentialsCatalogue.fetchAndParseCatalogue(TRUST_ANCHOR_BASE_URL);
+```

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

@@ -0,0 +1,54 @@
+import { decode as decodeJwt, verify } from "@pagopa/io-react-native-jwt";
+import { hasStatusOrThrow } from "../utils/misc";
+import { IoWalletError } from "../utils/errors";
+import { DigitalCredentialsCatalogue } from "./types";
+import { getTrustAnchorEntityConfiguration } from "../trust/build-chain";
+
+type GetCatalogueContext = {
+  appFetch?: GlobalFetch["fetch"];
+};
+
+/**
+ * Fetch and parse the Digital Credential Catalogue from the Trust Anchor.
+ * The catalogue's JWT signature is verified against the Trust Anchor's JWKs.
+ *
+ * @param trustAnchorUrl Base URL of the Trust Anchor
+ * @param context.appFetch (optional) fetch API implementation. Default: built-in fetch
+ * @returns The Digital Credential Catalogue payload
+ */
+export const fetchAndParseCatalogue = async (
+  trustAnchorBaseUrl: string,
+  { appFetch = fetch }: GetCatalogueContext = {}
+): Promise<DigitalCredentialsCatalogue["payload"]> => {
+  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);
+
+  const parsedDigitalCredentialsCatalogue = DigitalCredentialsCatalogue.parse({
+    header: responseJwt.protectedHeader,
+    payload: responseJwt.payload,
+  });
+
+  return parsedDigitalCredentialsCatalogue.payload;
+};

package/src/credentials-catalogue/index.ts

@@ -0,0 +1,2 @@
+export { fetchAndParseCatalogue } from "./fetch-and-parse-catalogue";
+export { type DigitalCredentialsCatalogue } from "./types";

package/src/credentials-catalogue/types.ts

@@ -0,0 +1,97 @@
+import * as z from "zod";
+import { UnixTime } from "../sd-jwt/types";
+
+const CredentialPurpose = z.object({
+  id: z.string(),
+  description: z.string(),
+  category: z.string(),
+  subcategory: 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(),
+  organization_country: z.string(),
+  source_type: z.enum(["public", "private"]),
+  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 DigitalCredentialsCatalogue = 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 DigitalCredentialsCatalogue = z.infer<
+  typeof DigitalCredentialsCatalogue
+>;

package/src/index.ts

@@ -5,8 +5,10 @@ import { fixBase64EncodingOnKey } from "./utils/jwk";
 import "react-native-url-polyfill/auto";
 
 import * as Credential from "./credential";
+import * as CredentialsCatalogue from "./credentials-catalogue";
 import * as PID from "./pid";
 import * as SdJwt from "./sd-jwt";
+import * as Mdoc from "./mdoc";
 import * as Errors from "./utils/errors";
 import * as WalletInstanceAttestation from "./wallet-instance-attestation";
 import * as Trust from "./trust";
@@ -18,8 +20,10 @@ import type { IntegrityContext } from "./utils/integrity";
 
 export {
   SdJwt,
+  Mdoc,
   PID,
   Credential,
+  CredentialsCatalogue,
   WalletInstanceAttestation,
   WalletInstance,
   Errors,

package/src/mdoc/index.ts

@@ -9,6 +9,7 @@ import {
 import { MissingX509CertsError, X509ValidationError } from "../trust/errors";
 import { IoWalletError } from "../utils/errors";
 import { convertBase64DerToPem, getSigninJwkFromCert } from "../utils/crypto";
+export * from "./utils";
 
 export const verify = async (
   token: string,

package/src/mdoc/utils.ts

@@ -1,3 +1,9 @@
+import { CBOR } from "@pagopa/io-react-native-iso18013";
+import { Verification } from "../sd-jwt/types";
+import type { VerifyAndParseCredential } from "../credential/issuance";
+import type { Out } from "../utils/misc";
+import { MDOC_DEFAULT_NAMESPACE } from "./const";
+
 /**
  * @param namespace The mdoc credential `namespace`
  * @param key The claim attribute key
@@ -5,3 +11,40 @@
  */
 export const getParsedCredentialClaimKey = (namespace: string, key: string) =>
   `${namespace}:${key}`;
+
+/**
+ * Extract and validate the `verification` claim from an mdoc parsed credential.
+ *
+ * This method is **synchronous**, so it requires a credential that was already parsed.
+ *
+ * @param parsedCredential The parsed mdoc credential
+ * @returns The verification claim or undefined if it wasn't found
+ */
+export const getVerificationFromParsedCredential = (
+  parsedCredential: Out<VerifyAndParseCredential>["parsedCredential"]
+) => {
+  const verificationKey = getParsedCredentialClaimKey(
+    `${MDOC_DEFAULT_NAMESPACE}.IT`,
+    "verification"
+  );
+  const verification = parsedCredential[verificationKey]?.value;
+  return verification ? Verification.parse(verification) : undefined;
+};
+
+/**
+ * Extract and validate the `verification` claim from an MDOC credential.
+ *
+ * This method is **asynchronous**. See {@link getVerificationFromParsedCredential} for the synchronous version.
+ *
+ * @param token The raw MDOC credential
+ * @returns The verification claim or undefined if it wasn't found
+ */
+export const getVerification = async (token: string) => {
+  const issuerSigned = await CBOR.decodeIssuerSigned(token);
+  const namespace = issuerSigned.nameSpaces[`${MDOC_DEFAULT_NAMESPACE}.IT`];
+  const verification = namespace?.find(
+    (x) => x.elementIdentifier === "verification"
+  )?.elementValue;
+
+  return verification ? Verification.parse(verification) : undefined;
+};

package/src/utils/nestedProperty.ts

@@ -25,7 +25,7 @@ const buildName = (display: DisplayData): LocalizedNames =>
     {}
   );
 
-// Handles the case where the path key is `null`
+// Handles the case where the path key is `null` (indicating an array)
 const handleNullKeyCase = (
   currentObject: NodeOrStructure,
   rest: Path,
@@ -39,7 +39,15 @@ const handleNullKeyCase = (
   const existingValue = Array.isArray(node.value) ? node.value : [];
 
   const mappedArray = sourceValue.map((item, idx) =>
-    createNestedProperty(existingValue[idx] || {}, rest, item, displayData)
+    // When mapping over an array, recursively call with `skipMissingLeaves` set to `true`.
+    // This tells the function to skip optional keys inside these array objects.
+    createNestedProperty(
+      existingValue[idx] || {},
+      rest,
+      item,
+      displayData,
+      true
+    )
   );
 
   return {
@@ -55,7 +63,8 @@ const handleStringKeyCase = (
   key: string,
   rest: Path,
   sourceValue: unknown,
-  displayData: DisplayData
+  displayData: DisplayData,
+  skipMissingLeaves: boolean
 ): NodeOrStructure => {
   let nextSourceValue = sourceValue;
   const isLeaf = rest.length === 0;
@@ -73,7 +82,13 @@ const handleStringKeyCase = (
 
     // Skip processing when the key is not found within the claim object
     if (!(key in sourceValue)) {
-      // Leaf node: create a node with an empty value and display name
+      // If the flag is set (we're inside an array), skip the missing key completely.
+      if (skipMissingLeaves) {
+        return currentObject;
+      }
+
+      // If the flag is NOT set, create the empty placeholder
+      // so that its children can be attached later.
       if (isLeaf) {
         return {
           ...currentObject,
@@ -101,7 +116,13 @@ const handleStringKeyCase = (
 
   return {
     ...currentObject,
-    [key]: createNestedProperty(nextObject, rest, nextSourceValue, displayData),
+    [key]: createNestedProperty(
+      nextObject,
+      rest,
+      nextSourceValue,
+      displayData,
+      skipMissingLeaves
+    ),
   };
 };
 
@@ -132,13 +153,15 @@ const handleNumberKeyCase = (
  * @param path - The path segments to follow.
  * @param sourceValue - The raw value to place at the end of the path.
  * @param displayData - The data for generating localized names.
+ * @param skipMissingLeaves - If true, skips optional keys when mapping over arrays.
  * @returns The new object or array structure.
  */
 export const createNestedProperty = (
   currentObject: NodeOrStructure,
   path: Path,
-  sourceValue: unknown, // Use `unknown` for type-safe input
-  displayData: DisplayData
+  sourceValue: unknown,
+  displayData: DisplayData,
+  skipMissingLeaves: boolean = false
 ): NodeOrStructure => {
   const [key, ...rest] = path;
 
@@ -152,7 +175,8 @@ export const createNestedProperty = (
         key as string,
         rest,
         sourceValue,
-        displayData
+        displayData,
+        skipMissingLeaves
       );
 
     case typeof key === "number":
@@ -178,11 +202,12 @@ const handleRestKey = (
   displayData: DisplayData
 ): NodeOrStructure => {
   const currentNode = currentObject[key] ?? {};
-  // Take the first key in the remaining path
   const restKey = rest[0] as string;
   const nextSourceValue = sourceValue[restKey];
+  if (typeof nextSourceValue === "undefined") {
+    return currentObject;
+  }
 
-  // Merge the current node with the updated nested property for the remaining path.
   return {
     ...currentObject,
     [key]: {

package/src/utils/zod.ts

@@ -0,0 +1,28 @@
+/**
+ * @see https://github.com/JacobWeisenburger/zod_utilz/blob/main/src/stringToJSON.ts
+ */
+
+import { z } from "zod";
+
+const literalSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+
+type Literal = z.infer<typeof literalSchema>;
+
+type Json = Literal | { [key: string]: Json } | Json[];
+
+const jsonSchema: z.ZodType<Json> = z.lazy(() =>
+  z.union([literalSchema, z.array(jsonSchema), z.record(jsonSchema)])
+);
+
+export const json = () => jsonSchema;
+
+export const stringToJSONSchema = z
+  .string()
+  .transform((str, ctx): z.infer<ReturnType<typeof json>> => {
+    try {
+      return JSON.parse(str);
+    } catch (e) {
+      ctx.addIssue({ code: "custom", message: "Invalid JSON" });
+      return z.NEVER;
+    }
+  });