@pagopa/io-react-native-wallet 2.2.0 → 2.4.0

package/src/credential/offer/README.md

@@ -0,0 +1,174 @@
+# Credential Offer
+
+This flow handles the initial step of credential issuance by processing Credential Offers from Credential Issuers. The Credential Offer contains information about what credentials are available and how they can be obtained. Each step in the flow is imported from the related file which is named with a sequential number.
+
+A Credential Offer can be received by the Wallet in two ways: **by value** (complete offer embedded in the URL) or **by reference** (URL pointing to the offer endpoint). The offer specifies which credentials are available and what authorization flows are supported by the issuer.
+
+The implementation follows the [OpenID for Verifiable Credential Issuance 1.0](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-offer-endpoint) specification and supports both Authorization Code flow and Pre-Authorized Code flow.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant U as User
+  participant W as Wallet
+  participant CI as Credential Issuer
+
+  CI->>U: QR Code / Deep Link with Credential Offer
+  U->>W: Scan QR / Click Link
+  W->>W: startFlowFromQR: Parse offer parameters
+  alt Credential Offer by Reference
+    W->>CI: fetchCredentialOffer: Fetch offer from URI
+    CI->>W: Return Credential Offer JSON
+  end
+  W->>W: Validate Credential Offer schema
+  W->>W: Determine available grant types
+  Note over W: Flow continues with credential issuance
+```
+
+## Grant Types
+
+The Credential Offer supports two OAuth 2.0 grant types that determine how authorization is handled:
+
+### Authorization Code Flow
+
+Used for interactive flows where user authentication and consent are required at the Authorization Server.
+
+- **`issuer_state`** (optional): Binds the authorization request to a specific issuer context
+- **`authorization_server`** (optional): Identifies which authorization server to use when multiple are available
+
+### Pre-Authorized Code Flow
+
+Used when the user has already been authenticated and authorized out-of-band. The issuer provides a pre-authorized code that can be exchanged directly for credentials.
+
+- **`pre-authorized_code`**: Short-lived single-use authorization code
+- **`tx_code`** (optional): Additional transaction code requirements for security
+- **`authorization_server`** (optional): Identifies which authorization server to use
+
+## Transaction Code Requirements
+
+When a transaction code is required for Pre-Authorized Code flow, the following parameters control the user experience:
+
+| Parameter     | Type                    | Description                                          |
+| ------------- | ----------------------- | ---------------------------------------------------- |
+| `input_mode`  | `"numeric"` \| `"text"` | Character set for the code (default: `"numeric"`)    |
+| `length`      | number                  | Expected code length to optimize input UI            |
+| `description` | string                  | User guidance (max 300 chars) for obtaining the code |
+
+## Credential Offer Transmission
+
+### By Value
+
+The complete Credential Offer is embedded in the URL parameter:
+
+```
+openid-credential-offer://?credential_offer=%7B%22credential_issuer%22...
+```
+
+### By Reference
+
+A URL points to an endpoint serving the Credential Offer:
+
+```
+openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fserver.example.com%2Foffer
+```
+
+When using by reference, the Wallet fetches the offer via HTTP GET with `Accept: application/json`.
+
+## Mapped Results
+
+The following errors are mapped during credential offer processing:
+
+| Error                         | Description                                                                        |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| `InvalidQRCodeError`          | The QR code format is invalid or doesn't contain valid credential offer parameters |
+| `InvalidCredentialOfferError` | The credential offer schema validation failed or contains invalid data             |
+
+## Examples
+
+<details>
+  <summary>Credential Offer processing flow</summary>
+
+```ts
+// Parse QR code or deep link
+const qrCode =
+  "openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fissuer.example.com%2Foffer";
+const { credential_offer_uri } = startFlowFromQR(qrCode);
+
+// Fetch the credential offer if by reference
+const offer = await fetchCredentialOffer(credential_offer_uri, { appFetch });
+
+console.log(offer);
+// {
+//   credential_issuer: "https://issuer.example.com",
+//   credential_configuration_ids: ["UniversityDegree", "DriverLicense"],
+//   grants: {
+//     authorization_code: {
+//       issuer_state: "xyz123"
+//     },
+//     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
+//       "pre-authorized_code": "SplxlOBeZQQYbYS6WxSbIA",
+//       tx_code: {
+//         length: 6,
+//         input_mode: "numeric",
+//         description: "Enter the code sent to your email"
+//       }
+//     }
+//   }
+// }
+```
+
+</details>
+
+<details>
+  <summary>Pre-Authorized Code with Transaction Code</summary>
+
+```ts
+const offer: CredentialOffer = {
+  credential_issuer: "https://university.example.edu",
+  credential_configuration_ids: ["DiplomaCredential"],
+  grants: {
+    "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
+      "pre-authorized_code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
+      tx_code: {
+        length: 4,
+        input_mode: "numeric",
+        description: "Check your email for the verification code",
+      },
+    },
+  },
+};
+
+// The user would need to:
+// 1. Check their email for a 4-digit numeric code
+// 2. Enter it in the wallet when prompted
+// 3. The wallet uses both pre-authorized_code and tx_code in the token request
+```
+
+</details>
+
+<details>
+  <summary>Authorization Code Flow</summary>
+
+```ts
+const offer: CredentialOffer = {
+  credential_issuer: "https://dmv.example.gov",
+  credential_configuration_ids: ["org.iso.18013.5.1.mDL"],
+  grants: {
+    authorization_code: {
+      issuer_state: "af0ifjsldkj",
+      authorization_server: "https://auth.dmv.example.gov",
+    },
+  },
+};
+
+// This would lead to:
+// 1. User authentication at the authorization server
+// 2. User consent for credential issuance
+// 3. Authorization code returned to wallet
+// 4. Wallet exchanges code for access token
+// 5. Wallet uses access token to request credential
+```
+
+</details>

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,6 +5,7 @@ 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";
@@ -22,6 +23,7 @@ export {
   Mdoc,
   PID,
   Credential,
+  CredentialsCatalogue,
   WalletInstanceAttestation,
   WalletInstance,
   Errors,

package/src/utils/auth.ts

@@ -35,3 +35,15 @@ export const AuthorizationErrorShape = z.object({
  * Type of the identification result.
  */
 export type AuthorizationResult = z.infer<typeof AuthorizationResultShape>;
+
+/**
+ * MRTD PoP Challenge Info response structure
+ */
+
+export const AuthorizationChallengeResultShape = z.object({
+  challenge_info: z.string(),
+});
+
+export type AuthorizationChallengeResult = z.infer<
+  typeof AuthorizationChallengeResultShape
+>;

package/src/utils/par.ts

@@ -12,10 +12,18 @@ import { IssuerResponseError } from "./errors";
 import { LogLevel, Logger } from "./logging";
 
 export type AuthorizationDetail = z.infer<typeof AuthorizationDetail>;
-export const AuthorizationDetail = z.object({
-  type: z.literal("openid_credential"),
-  credential_configuration_id: z.string(),
-});
+export const AuthorizationDetail = z.union([
+  z.object({
+    type: z.literal("openid_credential"),
+    credential_configuration_id: z.string(),
+  }),
+  z.object({
+    type: z.literal("it_l2+document_proof"),
+    idphinting: z.string(),
+    challenge_method: z.literal("mrtd+ias"),
+    challenge_redirect_uri: z.string(),
+  }),
+]);
 
 export type AuthorizationDetails = z.infer<typeof AuthorizationDetails>;
 export const AuthorizationDetails = z.array(AuthorizationDetail);

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