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

package/src/credential/issuance/api/02-start-user-authorization.ts

@@ -0,0 +1,50 @@
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
+import type { AuthorizationDetail } from "../../../utils/par";
+import type { IssuerConfig } from "./IssuerConfig";
+
+export interface StartUserAuthorizationApi {
+  /**
+   * WARNING: This function must be called after {@link evaluateIssuerTrust}. The next steam is {@link completeUserAuthorizationWithQueryMode} or {@link completeUserAuthorizationWithFormPostJwtMode}
+   *
+   * Creates and sends a PAR request to the PAR endpoint of the authorization server.
+   * This starts the authentication flow to obtain an access token.
+   * This token enables the Wallet Instance to request a digital credential from the Credential Endpoint of the Credential Issuer; when multiple credential types are passed,
+   * it is possible to use the same access token for the issuance of all requested credentials.
+   *
+   * This is an HTTP POST request containing the Wallet Instance identifier (client id), the code challenge and challenge method as specified by PKCE according to RFC 9126
+   * along with the WTE and its proof of possession (WTE-PoP).
+   * Additionally, it includes a request object, which is a signed JWT encapsulating the type of digital credential requested (authorization_details), challenge method and
+   * redirect URI for the document proof step (if L2 flow), the application session identifier on the Wallet Instance side (state), the method (query or form_post.jwt)
+   * by which the Authorization Server should transmit the Authorization Response containing the authorization code issued upon the end user's authentication (response_mode)
+   * to the Wallet Instance's Token Endpoint to obtain the Access Token, and the redirectUri of the Wallet Instance where the Authorization Response should be delivered.
+   * The redirect is achived by using a custom URL scheme that the Wallet Instance is registered to handle.
+   * @since 1.0.0
+   *
+   * @param issuerConf The issuer configuration
+   * @param credentialIds The credential configuration IDs to be requested
+   * @param proof The configuration for the proof to be used in the request: "none" for standard flows, "document" for L2+ with MRTD verification.
+   * @param context.wiaCryptoContext The Wallet Instance's cryptographic context
+   * @param context.walletInstanceAttestation: the Wallet Instance's attestation
+   * @param context.redirectUri: the redirect URI
+   * @param context.appFetch: (optional) the fetch implementation
+   * @returns The URI to which the end user should be redirected to start the authentication flow, along with additional authentication parameters
+   */
+  startUserAuthorization(
+    issuerConf: IssuerConfig,
+    credentialIds: string[],
+    proof:
+      | { proofType: "none" }
+      | { proofType: "mrtd-pop"; idpHinting: string },
+    context: {
+      wiaCryptoContext: CryptoContext;
+      walletInstanceAttestation: string;
+      redirectUri: string;
+      appFetch?: GlobalFetch["fetch"];
+    }
+  ): Promise<{
+    issuerRequestUri: string;
+    clientId: string;
+    codeVerifier: string;
+    credentialDefinition: AuthorizationDetail[];
+  }>;
+}

package/src/credential/issuance/api/03-complete-user-authorization.ts

@@ -0,0 +1,102 @@
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
+import type {
+  AuthorizationChallengeResult,
+  AuthorizationResult,
+} from "../../../utils/auth";
+import type { RequestObject } from "../../../credential/presentation/api";
+import type { IssuerConfig } from "./IssuerConfig";
+
+export interface CompleteUserAuthorizationApi {
+  /**
+   * WARNING: This function must be called after {@link startUserAuthorization}. The next function to be called is {@link completeUserAuthorizationWithFormPostJwtMode}.
+   *
+   * The interface of the phase to complete User authorization via presentation of existing credentials when the response mode is "form_post.jwt".
+   * It is used as a first step to complete the user authorization by obtaining the requested credential to be presented from the authorization server.
+   * The information is obtained by performing a GET request to the authorization endpoint with request_uri and client_id parameters.
+   * @since 1.0.0
+   *
+   * @param issuerRequestUri the URI of the issuer where the request is sent
+   * @param clientId Identifies the current client across all the requests of the issuing flow returned by {@link startUserAuthorization}
+   * @param issuerConf The issuer configuration returned by {@link evaluateIssuerTrust}
+   * @param appFetch (optional) fetch api implementation. Default: built-in fetch
+   * @returns the request object which contains the credential to be presented in order to obtain the requested credential
+   * @throws {ValidationFailed} if an error while validating the response
+   */
+  getRequestedCredentialToBePresented(
+    issuerRequestUri: string,
+    clientId: string,
+    issuerConf: IssuerConfig,
+    appFetch?: GlobalFetch["fetch"]
+  ): Promise<RequestObject>;
+
+  /**
+   * WARNING: This function must be called after obtaining the authorization redirect URL from the webviews (SPID and CIE L3) or browser for CIEID.
+   *
+   * Complete User authorization via strong identification when the response mode is "query" and the request credential is a PersonIdentificationData.
+   * This function parses the authorization redirect URL to extract the authorization response.
+   * @since 1.0.0
+   *
+   * @param authRedirectUrl The URL to which the end user should be redirected to start the authentication flow
+   * @returns the authorization response which contains code, state and iss
+   */
+  completeUserAuthorizationWithQueryMode(
+    authRedirectUrl: string
+  ): Promise<AuthorizationResult>;
+
+  /**
+   * WARNING: This function must be called after {@link getRequestedCredentialToBePresented}. The next function to be called is {@link authorizeAccess}.
+   *
+   * The interface of the phase to complete User authorization via presentation of existing credentials when the response mode is "form_post.jwt".
+   * The information is obtained by performing a POST request to the endpoint received in the response_uri field of the requestObject, where the Authorization Response payload is posted.
+   * Following this,the redirect_uri from the response is used to obtain the final authorization response.
+   * @since 1.0.0
+   *
+   * @param requestObject - The request object containing the necessary parameters for authorization.
+   * @param pid The `PID` that must be presented for the issuance of credentials.
+   * @param appFetch (optional) fetch api implementation. Default: built-in fetch
+   * @returns the authorization response which contains code, state and iss
+   * @throws {ValidationFailed} if an error while validating the response
+   */
+  completeUserAuthorizationWithFormPostJwtMode(
+    requestObject: RequestObject,
+    issuerConf: IssuerConfig,
+    pid: string,
+    context: {
+      wiaCryptoContext: CryptoContext;
+      pidKeyTag: string;
+      appFetch?: GlobalFetch["fetch"];
+    }
+  ): Promise<AuthorizationResult>;
+
+  /**
+   * WARNING: this function must be called after obtaining the authorization redirect URL from the webviews (SPID and CIE L3) or browser for CIEID, and the PID
+   * issuance requires a MRTD PoP challenge.
+   * @since 1.0.0
+   *
+   * @param authRedirectUrl The URL to which the end user should be redirected to start the MRTD PoP validation flow
+   * @returns the authorization response which contains the challenge
+   */
+  continueUserAuthorizationWithMRTDPoPChallenge(
+    authRedirectUrl: string
+  ): Promise<AuthorizationChallengeResult>;
+
+  /**
+   * WARNING: This function must be called after {@link startUserAuthorization}.
+   *
+   * The generated authUrl must be used to open a browser or webview capable of catching the redirectSchema to perform a get request to the authorization endpoint.
+   * Builds the authorization URL to which the end user should be redirected to continue the authentication flow.
+   * @since 1.0.0
+   *
+   * @param issuerRequestUri the URI of the issuer where the request is sent
+   * @param clientId Identifies the current client across all the requests of the issuing flow returned by {@link startUserAuthorization}
+   * @param issuerConf The issuer configuration returned by {@link evaluateIssuerTrust}
+   * @param idpHint Unique identifier of the IDP selected by the user (optional)
+   * @returns An object containing the authorization URL
+   */
+  buildAuthorizationUrl(
+    issuerRequestUri: string,
+    clientId: string,
+    issuerConf: IssuerConfig,
+    idpHint?: string
+  ): Promise<{ authUrl: string }>;
+}

package/src/credential/issuance/api/04-authorize-access.ts

@@ -0,0 +1,37 @@
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
+import type { IssuerConfig } from "./IssuerConfig";
+import type { TokenResponse } from "./types";
+
+export interface AuthorizeAccessApi {
+  /**
+   * Creates and sends the DPoP Proof JWT to be presented with the authorization code to the /token endpoint of the authorization server
+   * for requesting the issuance of an access token bound to the public key of the Wallet Instance contained within the DPoP.
+   * This enables the Wallet Instance to request a digital credential.
+   * The DPoP Proof JWT is generated according to the section 4.3 of the DPoP RFC 9449 specification.
+   * @since 1.0.0
+   *
+   * @param issuerConf The issuer configuration returned by {@link evaluateIssuerTrust}
+   * @param code The authorization code returned by {@link completeUserAuthorizationWithQueryMode} or {@link completeUserAuthorizationWithFormPost}
+   * @param redirectUri The redirect URI which is the custom URL scheme that the Wallet Instance is registered to handle
+   * @param codeVerifier The code verifier returned by {@link startUserAuthorization}
+   * @param context.walletInstanceAttestation The Wallet Instance's attestation
+   * @param context.wiaCryptoContext The Wallet Instance's crypto context
+   * @param context.dPopCryptoContext The DPoP crypto context
+   * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
+   * @return The token response containing the access token along with the token request signed with DPoP which has to be used in the {@link obtainCredential} step.
+   * @throws {ValidationFailed} if an error occurs while parsing the token response
+   * @throws {IssuerResponseError} with a specific code for more context
+   */
+  authorizeAccess(
+    issuerConf: IssuerConfig,
+    code: string,
+    redirectUri: string,
+    codeVerifier: string,
+    context: {
+      walletInstanceAttestation: string;
+      wiaCryptoContext: CryptoContext;
+      dPopCryptoContext: CryptoContext;
+      appFetch?: GlobalFetch["fetch"];
+    }
+  ): Promise<{ accessToken: TokenResponse }>;
+}

package/src/credential/issuance/api/05-obtain-credential.ts

@@ -0,0 +1,42 @@
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
+import type { Out } from "../../../utils/misc";
+import type { IssuerConfig } from "./IssuerConfig";
+import type { AuthorizeAccessApi } from "./04-authorize-access";
+import type { CredentialFormat } from "./types";
+
+export interface ObtainCredentialApi {
+  /**
+   * Obtains the credential from the issuer.
+   * The key pair of the credentialCryptoContext is used for Openid4vci proof JWT to be presented with the Access Token and the DPoP Proof JWT at the Credential Endpoint
+   * of the Credential Issuer to request the issuance of a credential linked to the public key contained in the JWT proof.
+   * The Openid4vci proof JWT incapsulates the nonce extracted from the token response from the {@link authorizeAccess} step.
+   * The credential request is sent to the Credential Endpoint of the Credential Issuer via HTTP POST with the type of the credential, its format, the access token and the JWT proof.
+   * @since 1.0.0
+   *
+   * @param issuerConf The issuer configuration returned by {@link evaluateIssuerTrust}
+   * @param accessToken The access token response returned by {@link authorizeAccess}
+   * @param clientId The client id returned by {@link startUserAuthorization}
+   * @param credentialDefinition The credential definition of the credential to be obtained returned by {@link authorizeAccess}
+   * @param context.credentialCryptoContext The crypto context used to obtain the credential
+   * @param context.dPopCryptoContext The DPoP crypto context
+   * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
+   * @returns The credential response containing the credential
+   */
+  obtainCredential(
+    issuerConf: IssuerConfig,
+    accessToken: Out<AuthorizeAccessApi["authorizeAccess"]>["accessToken"],
+    clientId: string,
+    credentialDefinition: {
+      credential_configuration_id: string;
+      credential_identifier?: string;
+    },
+    context: {
+      dPopCryptoContext: CryptoContext;
+      credentialCryptoContext: CryptoContext;
+      appFetch?: GlobalFetch["fetch"];
+    }
+  ): Promise<{
+    credential: string;
+    format: CredentialFormat;
+  }>;
+}

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

@@ -0,0 +1,42 @@
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
+import type { IssuerConfig } from "./IssuerConfig";
+import type { ParsedCredential } from "./types";
+
+export interface VerifyAndParseCredentialApi {
+  /**
+   * Verify and parse an encoded credential.
+   * @since 1.0.0
+   *
+   * @param issuerConf The Issuer configuration returned by {@link evaluateIssuerTrust}
+   * @param credential The encoded credential returned by {@link obtainCredential}
+   * @param credentialConfigurationId The credential configuration ID that defines the provided credential
+   * @param context.credentialCryptoContext The crypto context used to obtain the credential in {@link obtainCredential}
+   * @param context.ignoreMissingAttributes Skip error when attributes declared in the issuer configuration are not found within disclosures
+   * @param context.includeUndefinedAttributes Include attributes not explicitly declared in the issuer configuration
+   * @returns A parsed credential with attributes in plain value, the expiration and issuance date of the credential
+   * @throws {IoWalletError} If the credential signature is not verified with the Issuer key set
+   * @throws {IoWalletError} If the credential is not bound to the provided user key
+   * @throws {IoWalletError} If the credential data fail to parse
+   */
+  verifyAndParseCredential(
+    issuerConf: IssuerConfig,
+    credential: string,
+    credentialConfigurationId: string,
+    context: {
+      credentialCryptoContext: CryptoContext;
+      /**
+       * Do not throw an error when an attribute is not found within disclosures.
+       */
+      ignoreMissingAttributes?: boolean;
+      /**
+       * Include attributes that are not explicitly mapped in the issuer configuration.
+       */
+      includeUndefinedAttributes?: boolean;
+    },
+    x509CertRoot?: string
+  ): Promise<{
+    parsedCredential: ParsedCredential;
+    expiration: Date;
+    issuedAt: Date | undefined;
+  }>;
+}

package/src/credential/issuance/api/IssuerConfig.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { JWK } from "../../../utils/jwk";
+import { FederationEntityMetadata } from "../../../trust/common/types";
+
+const DisplayConfig = z.object({
+  name: z.string(),
+  locale: z.string(),
+});
+
+const ClaimConfig = z.object({
+  path: z.array(z.union([z.string(), z.number(), z.null()])),
+  display: z.array(DisplayConfig),
+});
+
+const IssuanceErrorSupported = z.object({
+  display: z.array(
+    z.object({
+      title: z.string(),
+      description: z.string(),
+      locale: z.string(),
+    })
+  ),
+});
+
+const CredentialConfig = z.intersection(
+  z.discriminatedUnion("format", [
+    z.object({ format: z.literal("dc+sd-jwt"), vct: z.string() }),
+    z.object({ format: z.literal("mso_mdoc"), doctype: z.string() }),
+  ]),
+  z.object({
+    scope: z.string(),
+    display: z.array(DisplayConfig),
+    claims: z.array(ClaimConfig),
+    /**
+     * @deprecated Use the Credentials Catalogue to get the Auth Source
+     */
+    authentic_source: z.string().optional(),
+    /**
+     * @deprecated Kept for backward compatibility with v0.7.1
+     */
+    issuance_errors_supported: z.record(IssuanceErrorSupported).optional(),
+  })
+);
+
+/**
+ * Common Issuer configuration, decoupled from specific IT-Wallet versions.
+ */
+export type IssuerConfig = z.infer<typeof IssuerConfig>;
+export const IssuerConfig = z.object({
+  credential_issuer: z.string(),
+  pushed_authorization_request_endpoint: z.string(),
+  authorization_endpoint: z.string(),
+  token_endpoint: z.string(),
+  nonce_endpoint: z.string(),
+  status_assertion_endpoint: z.string().optional(),
+  credential_endpoint: z.string(),
+  keys: z.array(JWK),
+  credential_configurations_supported: z.record(CredentialConfig),
+  federation_entity: FederationEntityMetadata,
+  credential_issuance_batch_size: z.number().optional(),
+  /**
+   * @deprecated
+   */
+  response_modes_supported: z.array(z.string()).optional(),
+});

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

@@ -0,0 +1,21 @@
+import { type EvaluateIssuerTrustApi } from "./01-evaluate-issuer-trust";
+import { type StartUserAuthorizationApi } from "./02-start-user-authorization";
+import { type CompleteUserAuthorizationApi } from "./03-complete-user-authorization";
+import { type AuthorizeAccessApi } from "./04-authorize-access";
+import { type ObtainCredentialApi } from "./05-obtain-credential";
+import { type VerifyAndParseCredentialApi } from "./06-verify-and-parse-credential";
+import { type MRTDPoPApi } from "./mrtd-pop";
+
+export interface IssuanceApi
+  extends EvaluateIssuerTrustApi,
+    StartUserAuthorizationApi,
+    CompleteUserAuthorizationApi,
+    AuthorizeAccessApi,
+    ObtainCredentialApi,
+    VerifyAndParseCredentialApi {
+  MRTDPoP: MRTDPoPApi;
+}
+
+export type { IssuerConfig } from "./IssuerConfig";
+export type * as MRTDPoP from "./mrtd-pop";
+export type * from "./types";

package/src/credential/issuance/api/mrtd-pop/index.ts

@@ -0,0 +1,104 @@
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
+import type { IssuerConfig } from "../IssuerConfig";
+import type {
+  IasPayload,
+  MrtdPayload,
+  MrtdPoPChallenge,
+  MrtdPopVerificationResult,
+  MrtdProofChallengeInfo,
+} from "./types";
+
+export interface MRTDPoPApi {
+  /**
+   * Verifies and parses the payload of a MRTD Proof Challenge Info JWT obtained after the primary authentication.
+   *
+   * This function performs the following steps:
+   * 1. Validates the JWT signature using the issuer's JWKS.
+   * 2. Decodes the JWT and parses its structure according to the {@link MrtdProofChallengeInfo} schema.
+   * 3. Verifies that the `aud` claim matches the client's public key ID.
+   * 4. Checks that the JWT is not expired and was not issued in the future.
+   *
+   * @param issuerConf - The issuer configuration containing the JWKS for signature verification.
+   * @param challengeInfoJwt - The JWT string representing the MRTD Proof Challenge Info.
+   * @param context - The context containing the WIA crypto context used to retrieve the client public key.
+   * @returns The parsed payload of the MRTD Proof Challenge Info JWT.
+   * @throws {Error} If the JWT signature is invalid, the structure is malformed, the `aud` claim does not match,
+   * or the JWT is expired/not yet valid.
+   */
+  verifyAndParseChallengeInfo(
+    issuerConf: IssuerConfig,
+    challengeInfoJwt: string,
+    context: {
+      wiaCryptoContext: CryptoContext;
+    }
+  ): Promise<MrtdProofChallengeInfo>;
+
+  /**
+   * Initializes the MRTD challenge with the data received from the issuer after the primary authentication.
+   * This function must be called after {@link verifyAndParseChallengeInfo}.
+   *
+   * @param issuerConf - The issuer configuration containing the JWKS for signature verification.
+   * @param initUrl - The endpoint to call to initialize the challenge.
+   * @param mrtd_auth_session - Session identifier for session binding obtained from the MRTD Proof JWT.
+   * @param mrtd_pop_jwt_nonce - Nonce value obtained from the MRTD Proof JWT.
+   * @param context - The context containing the WIA crypto context used to retrieve the client public key,
+   * the wallet instance attestation and an optional fetch implementation.
+   * @returns The payload of the MRTD PoP Challenge JWT.
+   */
+  initChallenge(
+    issuerConf: IssuerConfig,
+    initUrl: string,
+    mrtd_auth_session: string,
+    mrtd_pop_jwt_nonce: string,
+    context: {
+      wiaCryptoContext: CryptoContext;
+      walletInstanceAttestation: string;
+      appFetch?: GlobalFetch["fetch"];
+    }
+  ): Promise<MrtdPoPChallenge>;
+
+  /**
+   * Validates the MRTD signed challenge by sending the MRTD and IAS payloads to the issuer.
+   * This function must be called after {@link initChallenge} and after obtaining the MRTD and IAS payloads
+   * through the CIE PACE process.
+   *
+   * @param issuerConf - The issuer configuration containing the JWKS for signature verification.
+   * @param verifyUrl - The endpoint to call to validate the challenge.
+   * @param mrtd_auth_session - Session identifier for session binding obtained from the MRTD Proof JWT.
+   * @param mrtd_pop_nonce - Nonce value obtained from the MRTD Proof JWT.
+   * @param mrtd - MRTD validation data containing Data Groups and SOD.
+   * @param ias - IAS validation data containing Anti-Cloning Public Key, and SOD.
+   * @param context - The context containing the WIA crypto context used to retrieve the client public key,
+   * the wallet instance attestation and an optional fetch implementation.
+   * @returns The MRTD PoP Verification Result containing the validation nonce and redirect URI to complete the flow.
+   */
+  validateChallenge(
+    issuerConf: IssuerConfig,
+    verifyUrl: string,
+    mrtd_auth_session: string,
+    mrtd_pop_nonce: string,
+    mrtd: MrtdPayload,
+    ias: IasPayload,
+    context: {
+      wiaCryptoContext: CryptoContext;
+      walletInstanceAttestation: string;
+      appFetch?: GlobalFetch["fetch"];
+    }
+  ): Promise<MrtdPopVerificationResult>;
+
+  /**
+   * WARNING: This function must be called after {@link validateChallenge}. The generated authUrl must be used to open a browser or webview capable of catching the redirectSchema to perform a get request to the authorization endpoint.
+   * Builds the callback URL to which the end user should be redirected to continue the authentication flow after the MRTD challenge validation.
+   * @param redirectUri - The redirect URI provided by the issuer after the challenge validation to continue the authentication flow.
+   * @param valPopNonce - The MRTD validation PoP nonce obtained from the challenge validation response.
+   * @param authSession - The MRTD authentication session identifier used for session binding.
+   * @returns An object containing the callback URL
+   */
+  buildChallengeCallbackUrl(
+    redirectUri: string,
+    valPopNonce: string,
+    authSession: string
+  ): Promise<{ callbackUrl: string }>;
+}
+
+export * from "./types";

package/src/credential/issuance/api/mrtd-pop/types.ts

@@ -0,0 +1,37 @@
+export type MrtdPayload = {
+  dg1: string;
+  dg11: string;
+  sod_mrtd: string;
+};
+
+export type IasPayload = {
+  ias_pk: string;
+  sod_ias: string;
+  challenge_signed: string;
+};
+
+export type MrtdProofChallengeInfo = {
+  iss: string;
+  aud: string;
+  iat: number;
+  exp: number;
+  status: "require_interaction";
+  type: "mrtd+ias";
+  mrtd_auth_session: string;
+  state: string;
+  mrtd_pop_jwt_nonce: string;
+  htu: string;
+  htm: "POST";
+};
+
+export type MrtdPoPChallenge = {
+  challenge: string;
+  mrtd_pop_nonce: string;
+  pop_verify_endpoint: string;
+  mrz?: string;
+};
+
+export type MrtdPopVerificationResult = {
+  mrtd_val_pop_nonce: string;
+  redirect_uri: string;
+};

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

@@ -0,0 +1,34 @@
+import * as z from "zod";
+
+export type CredentialFormat = "dc+sd-jwt" | "mso_mdoc";
+
+// The credential as a collection of attributes in plain value
+export type ParsedCredential = {
+  /** Attribute key */
+  [claim: string]: {
+    name:
+      | /* if i18n is provided */ Record<
+          string /* locale */,
+          string /* value */
+        >
+      | /* if no i18n is provided */ string
+      | undefined; // Add undefined as a possible value for the name property
+    value: unknown;
+  };
+};
+
+export type AuthorizationDetail = z.infer<typeof AuthorizationDetail>;
+export const AuthorizationDetail = z.object({
+  type: z.literal("openid_credential"),
+  credential_configuration_id: z.string(),
+  credential_identifiers: z.array(z.string()),
+});
+
+export type TokenResponse = z.infer<typeof TokenResponse>;
+export const TokenResponse = z.object({
+  access_token: z.string(),
+  refresh_token: z.string().optional(),
+  authorization_details: z.array(AuthorizationDetail),
+  expires_in: z.number().optional(),
+  token_type: z.string(),
+});

package/src/credential/issuance/common/02-start-user-authorization.ts

@@ -0,0 +1,86 @@
+import { LogLevel, Logger } from "../../../utils/logging";
+import { AuthorizationDetail } from "../../../utils/par";
+import type { IssuerConfig } from "../api";
+
+type ResponseMode = "query" | "form_post.jwt";
+
+/**
+ * Ensures that the credential type requested is supported by the issuer and contained in the
+ * issuer configuration.
+ * @param issuerConf The issuer configuration returned by {@link evaluateIssuerTrust}
+ * @param credentialId The credential configuration ID to be requested;
+ * @returns The credential definition to be used in the request which includes the format and the type and its type
+ */
+export const selectCredentialDefinition = (
+  issuerConf: IssuerConfig,
+  credentialId: string
+): AuthorizationDetail => {
+  const credential_configurations_supported =
+    issuerConf.credential_configurations_supported;
+
+  const [result] = Object.keys(credential_configurations_supported)
+    .filter((e) => e.includes(credentialId))
+    .map(() => ({
+      credential_configuration_id: credentialId,
+      type: "openid_credential" as const,
+    }));
+
+  if (!result) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Requested credential ${credentialId} is not supported by the issuer according to its configuration ${JSON.stringify(credential_configurations_supported)}`
+    );
+    throw new Error(`No credential support the type '${credentialId}'`);
+  }
+  return result;
+};
+
+/**
+ * Ensures that the response mode requested is supported by the issuer and contained in the issuer configuration.
+ * When multiple credentials are provided, all of them must support the same response_mode.
+ * @param issuerConf The issuer configuration
+ * @param credentialIds The credential configuration IDs to be requested
+ * @returns The response mode to be used in the request, "query" for PersonIdentificationData and "form_post.jwt" for all other types.
+ */
+export const selectResponseMode = (
+  issuerConf: IssuerConfig,
+  credentialIds: string[]
+): ResponseMode => {
+  const responseModeSet = new Set<ResponseMode>();
+
+  for (const credentialId of credentialIds) {
+    responseModeSet.add(
+      credentialId.match(/PersonIdentificationData/i)
+        ? "query"
+        : "form_post.jwt"
+    );
+  }
+
+  if (responseModeSet.size !== 1) {
+    Logger.log(
+      LogLevel.ERROR,
+      `${credentialIds} have incompatible response_mode: ${[...responseModeSet.values()]}`
+    );
+    throw new Error(
+      "Requested credentials have incompatible response_mode and cannot be requested with the same PAR request"
+    );
+  }
+
+  const [responseMode] = responseModeSet.values();
+
+  Logger.log(
+    LogLevel.DEBUG,
+    `Selected response mode ${responseMode} for credential IDs ${credentialIds}`
+  );
+
+  const responseModeSupported = issuerConf.response_modes_supported;
+  if (responseModeSupported && !responseModeSupported.includes(responseMode!)) {
+    Logger.log(
+      LogLevel.ERROR,
+      `Requested response mode ${responseMode} is not supported by the issuer according to its configuration ${JSON.stringify(responseModeSupported)}`
+    );
+    throw new Error(`No response mode support for IDs '${credentialIds}'`);
+  }
+
+  return responseMode!;
+};