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

package/src/credential/issuance/v1.3.3/06-verify-and-parse-credential.ts

@@ -0,0 +1,46 @@
+import { IoWalletError } from "../../../utils/errors";
+import { Logger, LogLevel } from "../../../utils/logging";
+import type { IssuanceApi } from "../api";
+import { verifyAndParseCredentialMDoc } from "../common/06-verify-and-parse-credential.mdoc";
+import { verifyAndParseCredentialSdJwt } from "../common/06-verify-and-parse-credential.sdjwt";
+
+export const verifyAndParseCredential: IssuanceApi["verifyAndParseCredential"] =
+  async (
+    issuerConf,
+    credential,
+    credentialConfigurationId,
+    context,
+    x509CertRoot
+  ) => {
+    const format =
+      issuerConf.credential_configurations_supported[credentialConfigurationId]
+        ?.format;
+
+    switch (format) {
+      case "dc+sd-jwt": {
+        Logger.log(LogLevel.DEBUG, "Parsing credential in dc+sd-jwt format");
+        return verifyAndParseCredentialSdJwt(
+          issuerConf,
+          credential,
+          credentialConfigurationId,
+          context
+        );
+      }
+      case "mso_mdoc": {
+        Logger.log(LogLevel.DEBUG, "Parsing credential in mso_mdoc format");
+        return verifyAndParseCredentialMDoc(
+          issuerConf,
+          credential,
+          credentialConfigurationId,
+          context,
+          x509CertRoot
+        );
+      }
+
+      default: {
+        const message = `Unsupported credential format: ${format}`;
+        Logger.log(LogLevel.ERROR, message);
+        throw new IoWalletError(message);
+      }
+    }
+  };

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

@@ -0,0 +1,28 @@
+import type { IssuanceApi } from "../api";
+import { evaluateIssuerTrust } from "./01-evaluate-issuer-trust";
+import { startUserAuthorization } from "./02-start-user-authorization";
+import {
+  continueUserAuthorizationWithMRTDPoPChallenge,
+  completeUserAuthorizationWithQueryMode,
+  completeUserAuthorizationWithFormPostJwtMode,
+  buildAuthorizationUrl,
+  getRequestedCredentialToBePresented,
+} from "./03-complete-user-authorization";
+import { authorizeAccess } from "./04-authorize-access";
+import { obtainCredential } from "./05-obtain-credential";
+import { verifyAndParseCredential } from "./06-verify-and-parse-credential";
+import { MRTDPoP } from "../mrtd-pop";
+
+export const Issuance: IssuanceApi = {
+  evaluateIssuerTrust,
+  startUserAuthorization,
+  buildAuthorizationUrl,
+  completeUserAuthorizationWithQueryMode,
+  continueUserAuthorizationWithMRTDPoPChallenge,
+  getRequestedCredentialToBePresented,
+  completeUserAuthorizationWithFormPostJwtMode,
+  authorizeAccess,
+  obtainCredential,
+  verifyAndParseCredential,
+  MRTDPoP,
+};

package/src/credential/issuance/v1.3.3/mappers.ts

@@ -0,0 +1,87 @@
+import type { MetadataResponse } from "@pagopa/io-wallet-oid4vci";
+import type { ParsedAuthorizeRequestResult } from "@pagopa/io-wallet-oid4vp";
+import { assert } from "../../../utils/misc";
+import { createMapper } from "../../../utils/mappers";
+import type { JWK } from "../../../utils/jwk";
+import type { RequestObject } from "../../../credential/presentation";
+import { IssuerConfig } from "../api/IssuerConfig";
+
+type CredentialConfigurations =
+  IssuerConfig["credential_configurations_supported"];
+type OpenIdCredentialIssuer =
+  MetadataResponse["metadata"]["openid_credential_issuer"];
+
+const mapCredentialConfigurationsSupported = (
+  oidIssuer: OpenIdCredentialIssuer
+): CredentialConfigurations =>
+  Object.entries(oidIssuer!.credential_configurations_supported).reduce(
+    (acc, [key, config]) => {
+      acc[key] = {
+        ...(config.format === "dc+sd-jwt"
+          ? { format: config.format, vct: config.vct }
+          : { format: config.format, doctype: config.doctype }),
+        scope: config.scope,
+        display: config.credential_metadata.display!,
+        claims:
+          config.credential_metadata.claims?.map((claim) => ({
+            path: claim.path,
+            display: claim.display ?? [],
+          })) ?? [],
+      };
+      return acc;
+    },
+    {} as CredentialConfigurations
+  );
+
+export const mapToIssuerConfig = createMapper<MetadataResponse, IssuerConfig>(
+  (x) => {
+    const {
+      oauth_authorization_server,
+      openid_credential_issuer,
+      federation_entity,
+    } = x.metadata;
+
+    assert(
+      oauth_authorization_server,
+      "oauth_authorization_server is required in Issuer metadata"
+    );
+    assert(
+      openid_credential_issuer,
+      "openid_credential_issuer is required in Issuer metadata"
+    );
+
+    return {
+      authorization_endpoint: oauth_authorization_server.authorization_endpoint,
+      credential_endpoint: openid_credential_issuer.credential_endpoint,
+      credential_issuer: openid_credential_issuer.credential_issuer,
+      credential_configurations_supported: mapCredentialConfigurationsSupported(
+        openid_credential_issuer
+      ),
+      keys: openid_credential_issuer.jwks.keys as JWK[],
+      pushed_authorization_request_endpoint:
+        oauth_authorization_server.pushed_authorization_request_endpoint,
+      token_endpoint: oauth_authorization_server.token_endpoint,
+      status_assertion_endpoint:
+        openid_credential_issuer.status_attestation_endpoint,
+      nonce_endpoint: openid_credential_issuer.nonce_endpoint!,
+      federation_entity: federation_entity ?? {},
+      credential_issuance_batch_size:
+        openid_credential_issuer.batch_credential_issuance?.batch_size,
+    };
+  },
+  { outputSchema: IssuerConfig } // Output validation for extra-safety
+);
+
+export const mapToRequestObject = createMapper<
+  ParsedAuthorizeRequestResult,
+  RequestObject
+>(({ payload }) => ({
+  iss: payload.iss ?? "UNKNOWN_ISSUER",
+  client_id: payload.client_id,
+  dcql_query: payload.dcql_query!,
+  nonce: payload.nonce,
+  response_uri: payload.response_uri!,
+  state: payload.state,
+  response_mode: payload.response_mode,
+  response_type: payload.response_type,
+}));

package/src/credential/issuance/v1.3.3/types.ts

@@ -0,0 +1,6 @@
+import * as z from "zod";
+
+export type NonceResponse = z.infer<typeof NonceResponse>;
+export const NonceResponse = z.object({
+  c_nonce: z.string(),
+});

package/src/credential/offer/README.md

@@ -1,174 +1,158 @@
 # 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.
+This module implements the **User Request Flow** for Issuer-Initiated credential issuance, as defined in [IT-Wallet Technical Specifications v1.3.3, Section 12.1.2](https://italia.github.io/eid-wallet-it-docs/) and [OpenID for Verifiable Credential Issuance 1.0, Section 4.1](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-offer-endpoint).
 
-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 flow processes a Credential Offer received from a Credential Issuer (or a Third Party / Authentic Source) and extracts the grant details needed to start the Issuance Flow.
 
-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.
+All operations delegate to the [`@pagopa/io-wallet-oid4vci`](https://github.com/nicolo-ribaudo/io-wallet-oid4vci) SDK.
 
-## Sequence Diagram
+## Flow overview
 
 ```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
+graph TD;
+  QR[QR code / deep link]
+  1[resolveCredentialOffer]
+  2[extractGrantDetails]
+  Issuance[Issuance Flow]
+
+  QR --> 1
+  1 -->|CredentialOffer| 2
+  2 -->|ExtractGrantDetailsResult| Issuance
 ```
 
-## Grant Types
+| Step | Function | What it does |
+|------|----------|--------------|
+| 1 | `resolveCredentialOffer` | Parses the URI, fetches the offer if by-reference, validates structure |
+| 2 | `extractGrantDetails` | Extracts the `authorization_code` grant details from the resolved offer |
 
-The Credential Offer supports two OAuth 2.0 grant types that determine how authorization is handled:
+## Credential Offer transmission
 
-### Authorization Code Flow
+A Credential Offer can reach the Wallet Instance in two ways (OpenID4VCI Section 4.1):
 
-Used for interactive flows where user authentication and consent are required at the Authorization Server.
+### By value (`credential_offer`)
 
-- **`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
+The complete Credential Offer JSON is embedded in the URI as an encoded query parameter:
 
-### Pre-Authorized Code Flow
+```
+openid-credential-offer://?credential_offer=%7B%22credential_issuer%22...%7D
+```
 
-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.
+### By reference (`credential_offer_uri`)
 
-- **`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
+A URL points to a resource serving the Credential Offer. The Wallet fetches it via HTTP GET with `Accept: application/json`. The Credential Issuer or Third Party SHOULD use a unique URI per offer to prevent caching.
 
-## Transaction Code Requirements
+```
+openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fissuer.example.com%2Foffer
+```
 
-When a transaction code is required for Pre-Authorized Code flow, the following parameters control the user experience:
+Both modes are handled transparently by `resolveCredentialOffer` (via the SDK).
 
-| 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 |
+## Supported URI schemes
 
-## Credential Offer Transmission
+The QR code or deep link must use one of the following schemes:
 
-### By Value
+- `openid-credential-offer://` (OpenID4VCI Section 4)
+- `haip-vci://` (OPENID4VC-HAIP Section 4.2)
+- `https://` (Universal Link, if listed in the Wallet's `credential_offer_endpoint`)
 
-The complete Credential Offer is embedded in the URL parameter:
+## Step 1 — Resolve and validate
 
-```
-openid-credential-offer://?credential_offer=%7B%22credential_issuer%22...
-```
+`resolveCredentialOffer(uri, { fetch })` performs two operations:
 
-### By Reference
+1. **Resolution** — parses the URI and, if the offer is by-reference, fetches the JSON from the remote endpoint.
+2. **Structural validation** — checks the resolved offer against IT-Wallet v1.3 rules:
+   - `credential_issuer` must be an HTTPS URL
+   - `grants` object is required
+   - `authorization_code` grant is required
+   - `scope` is required within `authorization_code`
 
-A URL points to an endpoint serving the Credential Offer:
+> **Note:** cross-validation against Credential Issuer metadata (e.g. verifying `credential_configuration_ids` against `credential_configurations_supported`, or matching `authorization_server` against the metadata's `authorization_servers`) is **not** part of this step. Per the spec, metadata processing happens once the User Request Flow is completed, at the start of the Issuance Flow.
 
-```
-openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fserver.example.com%2Foffer
+## Step 2 — Extract grant details
+
+`extractGrantDetails(offer)` reads the `grants` object and returns an `ExtractGrantDetailsResult`:
+
+```ts
+{
+  grantType: "authorization_code",
+  authorizationCodeGrant: {
+    scope: string,             // REQUIRED — used in the Authorization Request
+    issuerState?: string,      // binds the request to the Credential Issuer session
+    authorizationServer?: string // REQUIRED when the issuer uses multiple AS
+  }
+}
 ```
 
-When using by reference, the Wallet fetches the offer via HTTP GET with `Accept: application/json`.
+IT-Wallet v1.3 only supports the `authorization_code` grant type.
 
-## Mapped Results
+## Credential Offer parameters
 
-The following errors are mapped during credential offer processing:
+Reference: IT-Wallet spec, Section 12.1.2, Credential Offer parameters table.
 
-| 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             |
+| Field | Required | Description |
+|-------|----------|-------------|
+| `credential_issuer` | REQUIRED | HTTPS URL that uniquely identifies the Credential Issuer. Used to discover its metadata. |
+| `credential_configuration_ids` | REQUIRED | Array of credential type identifiers. Each must match an entry in the Issuer's `credential_configurations_supported`. |
+| `grants.authorization_code.scope` | REQUIRED | Maps to a specific credential type. The Wallet MUST use this value in the Authorization Request. |
+| `grants.authorization_code.issuer_state` | OPTIONAL | Opaque string from the Issuer. When present the Wallet MUST include it in the Authorization Request. |
+| `grants.authorization_code.authorization_server` | CONDITIONAL | REQUIRED when the Issuer uses more than one Authorization Server. Must match one entry in the Issuer's `authorization_servers` metadata. |
+
+## Error mapping
+
+| Error | Code | When |
+|-------|------|------|
+| `InvalidQRCodeError` | `ERR_INVALID_QR_CODE` | URI parsing fails (unsupported scheme, missing params, invalid or malformed query) |
+| `InvalidCredentialOfferError` | `ERR_INVALID_CREDENTIAL_OFFER` | Structural validation fails (missing grant, missing scope, non-HTTPS issuer) or grant extraction fails |
+
+> Note: Network or other unexpected errors thrown while fetching an offer by reference in `resolveCredentialOffer` are propagated as-is and are not mapped to `InvalidQRCodeError` or `InvalidCredentialOfferError`.
+## Boundary with the Issuance Flow
+
+The Credential Offer flow ends once `extractGrantDetails` returns. The Issuance Flow then begins with:
+
+1. Credential Issuer metadata processing (Trust Evaluation / Federation check)
+2. Cross-validation of the offer against metadata
+3. PAR Request, Authorization, Token exchange, Credential Request
 
 ## Examples
 
 <details>
-  <summary>Credential Offer processing flow</summary>
+  <summary>Offer by reference</summary>
 
 ```ts
-// Parse QR code or deep link
-const qrCode =
+import { CredentialOffer } from "@pagopa/io-react-native-wallet";
+
+const uri =
   "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 });
+// 1) Resolve — fetches the offer from the URI and validates it
+const offer = await CredentialOffer.V1_3_3.resolveCredentialOffer(uri, {
+  fetch: appFetch,
+});
 
-console.log(offer);
+// 2) Extract grant details
+const grant = CredentialOffer.V1_3_3.extractGrantDetails(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"
-//       }
-//     }
-//   }
+//   grantType: "authorization_code",
+//   authorizationCodeGrant: { scope: "org.iso.18013.5.1.mDL", ... }
 // }
 ```
 
 </details>
 
 <details>
-  <summary>Pre-Authorized Code with Transaction Code</summary>
+  <summary>Offer by value</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
-```
+import { CredentialOffer } from "@pagopa/io-react-native-wallet";
 
-</details>
+const uri =
+  "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fissuer.example.com%22%2C%22credential_configuration_ids%22%3A%5B%22UniversityDegree%22%5D%2C%22grants%22%3A%7B%22authorization_code%22%3A%7B%22scope%22%3A%22UniversityDegree%22%7D%7D%7D";
 
-<details>
-  <summary>Authorization Code Flow</summary>
+// 1) Resolve — decodes the inline offer and validates it
+const offer = await CredentialOffer.V1_3_3.resolveCredentialOffer(uri);
 
-```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
+// 2) Extract grant details
+const grant = CredentialOffer.V1_3_3.extractGrantDetails(offer);
 ```
 
 </details>

package/src/credential/offer/api/01-resolve-credential-offer.ts

@@ -0,0 +1,23 @@
+import type { CredentialOffer } from "./types";
+
+export interface ResolveCredentialOfferApi {
+  /**
+   * Resolve and validate a Credential Offer received via QR code or deep link.
+   *
+   * Handles both transmission modes defined in OpenID4VCI Section 4.1:
+   * - **by value** (`credential_offer`): the offer JSON is embedded in the URI.
+   * - **by reference** (`credential_offer_uri`): the URI points to a resource
+   *   that is fetched via HTTP GET.
+   *
+   * @param credentialOffer - The raw URI string from the QR code or deep link.
+   * @param callbacks - Optional object with a custom `fetch` implementation
+   *   used when the offer is transmitted by reference.
+   * @returns The resolved and validated {@link CredentialOffer}.
+   * @throws {InvalidQRCodeError} If the URI cannot be parsed or the offer cannot be fetched.
+   * @throws {InvalidCredentialOfferError} If the resolved offer fails validation.
+   */
+  resolveCredentialOffer(
+    credentialOffer: string,
+    callbacks?: { fetch?: GlobalFetch["fetch"] }
+  ): Promise<CredentialOffer>;
+}

package/src/credential/offer/api/02-extract-grant-details.ts

@@ -0,0 +1,13 @@
+import type { CredentialOffer, ExtractGrantDetailsResult } from "./types";
+
+export interface ExtractGrantDetailsApi {
+  /**
+   * Extract grant details from a resolved Credential Offer.
+   *
+   * @param offer - A previously resolved {@link CredentialOffer}.
+   * @returns The extracted {@link ExtractGrantDetailsResult} containing
+   *   the grant type and its parameters.
+   * @throws {InvalidCredentialOfferError} If no supported grant type is found.
+   */
+  extractGrantDetails(offer: CredentialOffer): ExtractGrantDetailsResult;
+}

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

@@ -0,0 +1,8 @@
+import type { ResolveCredentialOfferApi } from "./01-resolve-credential-offer";
+import type { ExtractGrantDetailsApi } from "./02-extract-grant-details";
+
+export interface OfferApi
+  extends ResolveCredentialOfferApi,
+    ExtractGrantDetailsApi {}
+
+export * from "./types";

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

@@ -0,0 +1,5 @@
+import type { CredentialOffer as SdkCredentialOffer } from "@pagopa/io-wallet-oid4vci";
+import type { ExtractGrantDetailsResult as SdkExtractGrantDetailsResult } from "@pagopa/io-wallet-oid4vci";
+
+export type CredentialOffer = SdkCredentialOffer;
+export type ExtractGrantDetailsResult = SdkExtractGrantDetailsResult;

package/src/credential/offer/common/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

@@ -1,16 +1,5 @@
-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 };
+import * as Errors from "./common/errors";
+export { Errors };
+export type * from "./api";
+export { Offer as V1_0_0 } from "./v1.0.0";
+export { Offer as V1_3_3 } from "./v1.3.3";

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

@@ -0,0 +1,11 @@
+import { UnimplementedFeatureError } from "../../../utils/errors";
+import type { OfferApi } from "../api";
+
+export const Offer: OfferApi = {
+  async resolveCredentialOffer() {
+    throw new UnimplementedFeatureError("resolveCredentialOffer", "1.0.0");
+  },
+  extractGrantDetails() {
+    throw new UnimplementedFeatureError("extractGrantDetails", "1.0.0");
+  },
+};

package/src/credential/offer/v1.3.3/01-resolve-credential-offer.ts

@@ -0,0 +1,60 @@
+import {
+  resolveCredentialOffer as sdkResolveCredentialOffer,
+  validateCredentialOffer,
+  CredentialOfferError,
+} from "@pagopa/io-wallet-oid4vci";
+import {
+  InvalidQRCodeError,
+  InvalidCredentialOfferError,
+} from "../common/errors";
+import type { OfferApi } from "../api";
+
+/**
+ * v1.3.3 implementation — first step of the User Request Flow
+ * (IT-Wallet spec, Section 12.1.2).
+ *
+ * Delegates to the SDK's {@link sdkResolveCredentialOffer} for URI parsing
+ * and by-reference fetching, then to {@link validateCredentialOffer} for
+ * IT-Wallet v1.3 structural checks:
+ * - `credential_issuer` must be an HTTPS URL
+ * - `grants` object is required
+ * - `authorization_code` grant is required
+ * - `scope` is required within `authorization_code`
+ *
+ * Supported URI schemes: `openid-credential-offer://`, `haip-vci://`, `https://`.
+ *
+ * Cross-validation against Credential Issuer metadata (e.g. matching
+ * `credential_configuration_ids` or `authorization_server`) is **not** performed
+ * here; per the spec it belongs to the Issuance Flow.
+ *
+ * Resolution errors (bad scheme, missing params, network failure) are mapped
+ * to {@link InvalidQRCodeError}; validation errors are mapped to
+ * {@link InvalidCredentialOfferError}.
+ */
+export const resolveCredentialOffer: OfferApi["resolveCredentialOffer"] =
+  async (credentialOffer, callbacks = {}) => {
+    const { fetch: fetchFn = fetch } = callbacks;
+
+    // Parse the URI and fetch the offer when transmitted by reference
+    const resolved = await sdkResolveCredentialOffer({
+      credentialOffer,
+      callbacks: { fetch: fetchFn },
+    }).catch((e: unknown) => {
+      if (e instanceof CredentialOfferError) {
+        throw new InvalidQRCodeError(e.message);
+      }
+      throw e;
+    });
+
+    // Structural validation (no metadata cross-checks at this stage)
+    await validateCredentialOffer({
+      credentialOffer: resolved,
+    }).catch((e: unknown) => {
+      if (e instanceof CredentialOfferError) {
+        throw new InvalidCredentialOfferError(e.message);
+      }
+      throw e;
+    });
+
+    return resolved;
+  };

package/src/credential/offer/v1.3.3/02-extract-grant-details.ts

@@ -0,0 +1,27 @@
+import {
+  extractGrantDetails as sdkExtractGrantDetails,
+  CredentialOfferError,
+} from "@pagopa/io-wallet-oid4vci";
+import { InvalidCredentialOfferError } from "../common/errors";
+import { withMappedErrors } from "../../../utils/errors";
+import type { OfferApi } from "../api";
+
+/**
+ * v1.3.3 implementation — second and final step of the User Request Flow
+ * (IT-Wallet spec, Section 12.1.2).
+ *
+ * IT-Wallet v1.3 only supports the `authorization_code` grant type;
+ * the returned result always has `grantType: "authorization_code"`.
+ * The extracted `scope` is later used in the Authorization Request,
+ * and `issuerState` (when present) binds the request to the Credential
+ * Issuer session.
+ *
+ * Delegates directly to the SDK's {@link sdkExtractGrantDetails} — no local
+ * mapping is needed because the SDK already returns `ExtractGrantDetailsResult`.
+ */
+export const extractGrantDetails: OfferApi["extractGrantDetails"] = (offer) =>
+  withMappedErrors(
+    () => sdkExtractGrantDetails(offer),
+    CredentialOfferError,
+    (e) => new InvalidCredentialOfferError(e.message)
+  );