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

package/lib/module/credential/issuance/mrtd-pop/03-validate-challenge.js

@@ -0,0 +1,85 @@
+import { SignJWT } from "@pagopa/io-react-native-jwt";
+import { v4 as uuidv4 } from "uuid";
+import { IssuerResponseError } from "../../../utils/errors";
+import { hasStatusOrThrow } from "../../../utils/misc";
+import { createPopToken } from "../../../utils/pop";
+import * as WalletInstanceAttestation from "../../../wallet-instance-attestation";
+import { MrtdPopVerificationResult } from "./types";
+/**
+ * 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.
+ */
+export const validateChallenge = async (issuerConf, verifyUrl, mrtd_auth_session, mrtd_pop_nonce, mrtd, ias, context) => {
+  const {
+    appFetch = fetch,
+    walletInstanceAttestation,
+    wiaCryptoContext
+  } = context;
+  const aud = issuerConf.openid_credential_issuer.credential_issuer;
+  const iss = WalletInstanceAttestation.decode(walletInstanceAttestation).payload.cnf.jwk.kid;
+  const signedWiaPoP = await createPopToken({
+    jti: `${uuidv4()}`,
+    aud,
+    iss
+  }, wiaCryptoContext);
+  const {
+    kid
+  } = await wiaCryptoContext.getPublicKey();
+  const mrtd_validation_jwt = await new SignJWT(wiaCryptoContext).setProtectedHeader({
+    typ: "mrtd-ias+jwt",
+    kid
+  }).setPayload({
+    iss,
+    aud,
+    document_type: "cie",
+    mrtd,
+    ias
+  }).setIssuedAt().setExpirationTime("5m").sign();
+  const requestBody = {
+    mrtd_validation_jwt,
+    mrtd_auth_session,
+    mrtd_pop_nonce
+  };
+  const verifyResult = await appFetch(verifyUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "OAuth-Client-Attestation": walletInstanceAttestation,
+      "OAuth-Client-Attestation-PoP": signedWiaPoP
+    },
+    body: JSON.stringify(requestBody)
+  }).then(hasStatusOrThrow(202, IssuerResponseError)).then(res => res.json());
+  const verifyResultParsed = MrtdPopVerificationResult.parse(verifyResult);
+  return verifyResultParsed;
+};
+
+/**
+ * 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
+ */
+export const buildChallengeCallbackUrl = async (redirectUri, valPopNonce, authSession) => {
+  const params = new URLSearchParams({
+    mrtd_val_pop_nonce: valPopNonce,
+    mrtd_auth_session: authSession
+  });
+  const callbackUrl = `${redirectUri}?${params}`;
+  return {
+    callbackUrl
+  };
+};
+//# sourceMappingURL=03-validate-challenge.js.map

package/lib/module/credential/issuance/mrtd-pop/03-validate-challenge.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["SignJWT","v4","uuidv4","IssuerResponseError","hasStatusOrThrow","createPopToken","WalletInstanceAttestation","MrtdPopVerificationResult","validateChallenge","issuerConf","verifyUrl","mrtd_auth_session","mrtd_pop_nonce","mrtd","ias","context","appFetch","fetch","walletInstanceAttestation","wiaCryptoContext","aud","openid_credential_issuer","credential_issuer","iss","decode","payload","cnf","jwk","kid","signedWiaPoP","jti","getPublicKey","mrtd_validation_jwt","setProtectedHeader","typ","setPayload","document_type","setIssuedAt","setExpirationTime","sign","requestBody","verifyResult","method","headers","body","JSON","stringify","then","res","json","verifyResultParsed","parse","buildChallengeCallbackUrl","redirectUri","valPopNonce","authSession","params","URLSearchParams","mrtd_val_pop_nonce","callbackUrl"],"sourceRoot":"../../../../../src","sources":["credential/issuance/mrtd-pop/03-validate-challenge.ts"],"mappings":"AAAA,SAASA,OAAO,QAA4B,6BAA6B;AACzE,SAASC,EAAE,IAAIC,MAAM,QAAQ,MAAM;AACnC,SAASC,mBAAmB,QAAQ,uBAAuB;AAC3D,SAASC,gBAAgB,QAAkB,qBAAqB;AAChE,SAASC,cAAc,QAAQ,oBAAoB;AACnD,OAAO,KAAKC,yBAAyB,MAAM,sCAAsC;AAEjF,SACEC,yBAAyB,QAGpB,SAAS;AAyBhB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAoC,GAAG,MAAAA,CAClDC,UAAU,EACVC,SAAS,EACTC,iBAAiB,EACjBC,cAAc,EACdC,IAAI,EACJC,GAAG,EACHC,OAAO,KACJ;EACH,MAAM;IACJC,QAAQ,GAAGC,KAAK;IAChBC,yBAAyB;IACzBC;EACF,CAAC,GAAGJ,OAAO;EAEX,MAAMK,GAAG,GAAGX,UAAU,CAACY,wBAAwB,CAACC,iBAAiB;EACjE,MAAMC,GAAG,GAAGjB,yBAAyB,CAACkB,MAAM,CAACN,yBAAyB,CAAC,CACpEO,OAAO,CAACC,GAAG,CAACC,GAAG,CAACC,GAAG;EAEtB,MAAMC,YAAY,GAAG,MAAMxB,cAAc,CACvC;IACEyB,GAAG,EAAG,GAAE5B,MAAM,CAAC,CAAE,EAAC;IAClBkB,GAAG;IACHG;EACF,CAAC,EACDJ,gBACF,CAAC;EAED,MAAM;IAAES;EAAI,CAAC,GAAG,MAAMT,gBAAgB,CAACY,YAAY,CAAC,CAAC;EAErD,MAAMC,mBAAmB,GAAG,MAAM,IAAIhC,OAAO,CAACmB,gBAAgB,CAAC,CAC5Dc,kBAAkB,CAAC;IAClBC,GAAG,EAAE,cAAc;IACnBN;EACF,CAAC,CAAC,CACDO,UAAU,CAAC;IACVZ,GAAG;IACHH,GAAG;IACHgB,aAAa,EAAE,KAAK;IACpBvB,IAAI;IACJC;EACF,CAAC,CAAC,CACDuB,WAAW,CAAC,CAAC,CACbC,iBAAiB,CAAC,IAAI,CAAC,CACvBC,IAAI,CAAC,CAAC;EAET,MAAMC,WAAW,GAAG;IAClBR,mBAAmB;IACnBrB,iBAAiB;IACjBC;EACF,CAAC;EAED,MAAM6B,YAAY,GAAG,MAAMzB,QAAQ,CAACN,SAAS,EAAE;IAC7CgC,MAAM,EAAE,MAAM;IACdC,OAAO,EAAE;MACP,cAAc,EAAE,kBAAkB;MAClC,0BAA0B,EAAEzB,yBAAyB;MACrD,8BAA8B,EAAEW;IAClC,CAAC;IACDe,IAAI,EAAEC,IAAI,CAACC,SAAS,CAACN,WAAW;EAClC,CAAC,CAAC,CACCO,IAAI,CAAC3C,gBAAgB,CAAC,GAAG,EAAED,mBAAmB,CAAC,CAAC,CAChD4C,IAAI,CAAEC,GAAG,IAAKA,GAAG,CAACC,IAAI,CAAC,CAAC,CAAC;EAE5B,MAAMC,kBAAkB,GAAG3C,yBAAyB,CAAC4C,KAAK,CAACV,YAAY,CAAC;EACxE,OAAOS,kBAAkB;AAC3B,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,yBAAoD,GAAG,MAAAA,CAClEC,WAAW,EACXC,WAAW,EACXC,WAAW,KACR;EACH,MAAMC,MAAM,GAAG,IAAIC,eAAe,CAAC;IACjCC,kBAAkB,EAAEJ,WAAW;IAC/B3C,iBAAiB,EAAE4C;EACrB,CAAC,CAAC;EAEF,MAAMI,WAAW,GAAI,GAAEN,WAAY,IAAGG,MAAO,EAAC;EAC9C,OAAO;IAAEG;EAAY,CAAC;AACxB,CAAC"}

package/lib/module/credential/issuance/mrtd-pop/README.md

@@ -0,0 +1,92 @@
+# MRTD PoP flow
+
+**MRTD-PoP (Machine Readable Travel Document - Proof of Possession)** flow for the IO Wallet, following the [eID Wallet L2+ Credential Issuance specification](https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/credential-issuance-l2plus.html).
+
+The MRTD-PoP flow is used to prove possession of an MRTD (such as a CIE) during the issuance of high-assurance credentials. The process involves a challenge-response protocol between the wallet and the issuer, leveraging JWTs and cryptographic attestation.
+
+This flow is part of the [PID issuance flow](../README.md) and must be started after the `continueUserAuthorizationWithMRTDPoPChallenge` function. Once MRTD PoP is completed, the PID issuance flow must continue with the `completeUserAuthorizationWithQueryMode` function with the authorization url obtained from the validation.
+
+> **⚠️ Important**: The entire flow must be initiated and concluded within the same web context (e.g., the same WebView instance) to maintain session continuity. Using different contexts (such as switching between an external browser and a WebView) will result in session loss and authentication failures due to cookie/session mismatch (JSESSIONID).
+
+## Sequence Diagram
+
+```mermaid
+graph TD;
+    A@{ shape: subproc, label: "continueUserAuthorizationWithMRTDPoPChallenge" }
+    subgraph MRTD PoP
+    B[verifyAndParseChallengeInfo]
+    C[initChallenge]
+    E[validateChallenge]
+    end
+    F@{ shape: subproc, label: "completeUserAuthorizationWithQueryModeChallenge" }
+
+
+    A -.-> B
+    B --> C
+    C -->E
+    E -.-> F
+
+```
+
+## Example
+
+```typescript
+// Verify and parse challenge info and extract challenge data: initialization url, session and nonce
+const {
+  htu: initUrl,
+  mrtd_auth_session,
+  mrtd_pop_jwt_nonce,
+} = await Credential.Issuance.MRTDPoP.verifyAndParseChallengeInfo(
+  issuerConf,
+  challenge_info,
+  { wiaCryptoContext }
+);
+
+// Initialize challenge and obtain the challenge text to sign the CIE PACE protocol and validation url
+const {
+  htu: validationUrl,
+  challenge,
+  mrtd_pop_nonce,
+} = await Credential.Issuance.MRTDPoP.initChallenge(
+  issuerConf,
+  initUrl,
+  mrtd_auth_session,
+  mrtd_pop_jwt_nonce,
+  {
+    walletInstanceAttestation,
+    wiaCryptoContext,
+    appFetch,
+  }
+);
+
+// CIE cryptographic interaction: you need to sign the challenge with the CIE through NFC interaction
+const { nis, mrtds } = /* NFC interactions functions */
+
+// Validate challenge
+const { mrtd_val_pop_nonce, redirect_uri } =
+  await Credential.Issuance.MRTDPoP.validateChallenge(
+    issuerConf,
+    validationUrl,
+    mrtd_auth_session,
+    mrtd_pop_nonce,
+    mrtd,
+    ias,
+    {
+      walletInstanceAttestation,
+      wiaCryptoContext,
+      appFetch,
+    }
+  );
+
+// Build the callback url
+const { callbackUrl } = await Credential.Issuance.buildChallengeCallbackUrl(
+  redirect_uri,
+  mrtd_val_pop_nonce,
+  mrtd_auth_session
+);
+
+// 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.
+const authRedirectUrl = /* From a browser or webview redirect */
+
+// Use the authRedirectUrl to continue the PID issuance flow
+```

package/lib/module/credential/issuance/mrtd-pop/index.js

@@ -0,0 +1,5 @@
+import { verifyAndParseChallengeInfo } from "./01-verify-and-parse-challenge-info";
+import { initChallenge } from "./02-init-challenge";
+import { validateChallenge, buildChallengeCallbackUrl } from "./03-validate-challenge";
+export { verifyAndParseChallengeInfo, initChallenge, validateChallenge, buildChallengeCallbackUrl };
+//# sourceMappingURL=index.js.map

package/lib/module/credential/issuance/mrtd-pop/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["verifyAndParseChallengeInfo","initChallenge","validateChallenge","buildChallengeCallbackUrl"],"sourceRoot":"../../../../../src","sources":["credential/issuance/mrtd-pop/index.ts"],"mappings":"AAAA,SACEA,2BAA2B,QAEtB,sCAAsC;AAC7C,SAASC,aAAa,QAA4B,qBAAqB;AACvE,SACEC,iBAAiB,EACjBC,yBAAyB,QAGpB,yBAAyB;AAGhC,SACEH,2BAA2B,EAC3BC,aAAa,EACbC,iBAAiB,EACjBC,yBAAyB"}

package/lib/module/credential/issuance/mrtd-pop/types.js

@@ -0,0 +1,46 @@
+import * as z from "zod";
+export const MrtdProofChallengeInfo = z.object({
+  protectedHeader: z.object({
+    typ: z.literal("mrtd-ias+jwt"),
+    alg: z.string(),
+    kid: z.string()
+  }),
+  payload: z.object({
+    iss: z.string(),
+    aud: z.string(),
+    iat: z.number(),
+    exp: z.number(),
+    status: z.literal("require_interaction"),
+    type: z.literal("mrtd+ias"),
+    mrtd_auth_session: z.string(),
+    state: z.string(),
+    mrtd_pop_jwt_nonce: z.string(),
+    htu: z.string(),
+    htm: z.literal("POST")
+  })
+});
+export const MrtdPoPChallenge = z.object({
+  protectedHeader: z.object({
+    typ: z.literal("mrtd-ias-pop+jwt"),
+    alg: z.string(),
+    kid: z.string()
+  }),
+  payload: z.object({
+    iss: z.string(),
+    aud: z.string(),
+    iat: z.number(),
+    exp: z.number(),
+    challenge: z.string(),
+    mrtd_pop_nonce: z.string(),
+    mrz: z.string().optional(),
+    htu: z.string(),
+    htm: z.literal("POST")
+  })
+});
+export const MrtdPopVerificationResult = z.object({
+  status: z.literal("require_interaction"),
+  type: z.literal("redirect_to_web"),
+  mrtd_val_pop_nonce: z.string(),
+  redirect_uri: z.string()
+});
+//# sourceMappingURL=types.js.map

package/lib/module/credential/issuance/mrtd-pop/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["z","MrtdProofChallengeInfo","object","protectedHeader","typ","literal","alg","string","kid","payload","iss","aud","iat","number","exp","status","type","mrtd_auth_session","state","mrtd_pop_jwt_nonce","htu","htm","MrtdPoPChallenge","challenge","mrtd_pop_nonce","mrz","optional","MrtdPopVerificationResult","mrtd_val_pop_nonce","redirect_uri"],"sourceRoot":"../../../../../src","sources":["credential/issuance/mrtd-pop/types.ts"],"mappings":"AAAA,OAAO,KAAKA,CAAC,MAAM,KAAK;AAGxB,OAAO,MAAMC,sBAAsB,GAAGD,CAAC,CAACE,MAAM,CAAC;EAC7CC,eAAe,EAAEH,CAAC,CAACE,MAAM,CAAC;IACxBE,GAAG,EAAEJ,CAAC,CAACK,OAAO,CAAC,cAAc,CAAC;IAC9BC,GAAG,EAAEN,CAAC,CAACO,MAAM,CAAC,CAAC;IACfC,GAAG,EAAER,CAAC,CAACO,MAAM,CAAC;EAChB,CAAC,CAAC;EACFE,OAAO,EAAET,CAAC,CAACE,MAAM,CAAC;IAChBQ,GAAG,EAAEV,CAAC,CAACO,MAAM,CAAC,CAAC;IACfI,GAAG,EAAEX,CAAC,CAACO,MAAM,CAAC,CAAC;IACfK,GAAG,EAAEZ,CAAC,CAACa,MAAM,CAAC,CAAC;IACfC,GAAG,EAAEd,CAAC,CAACa,MAAM,CAAC,CAAC;IACfE,MAAM,EAAEf,CAAC,CAACK,OAAO,CAAC,qBAAqB,CAAC;IACxCW,IAAI,EAAEhB,CAAC,CAACK,OAAO,CAAC,UAAU,CAAC;IAC3BY,iBAAiB,EAAEjB,CAAC,CAACO,MAAM,CAAC,CAAC;IAC7BW,KAAK,EAAElB,CAAC,CAACO,MAAM,CAAC,CAAC;IACjBY,kBAAkB,EAAEnB,CAAC,CAACO,MAAM,CAAC,CAAC;IAC9Ba,GAAG,EAAEpB,CAAC,CAACO,MAAM,CAAC,CAAC;IACfc,GAAG,EAAErB,CAAC,CAACK,OAAO,CAAC,MAAM;EACvB,CAAC;AACH,CAAC,CAAC;AAGF,OAAO,MAAMiB,gBAAgB,GAAGtB,CAAC,CAACE,MAAM,CAAC;EACvCC,eAAe,EAAEH,CAAC,CAACE,MAAM,CAAC;IACxBE,GAAG,EAAEJ,CAAC,CAACK,OAAO,CAAC,kBAAkB,CAAC;IAClCC,GAAG,EAAEN,CAAC,CAACO,MAAM,CAAC,CAAC;IACfC,GAAG,EAAER,CAAC,CAACO,MAAM,CAAC;EAChB,CAAC,CAAC;EACFE,OAAO,EAAET,CAAC,CAACE,MAAM,CAAC;IAChBQ,GAAG,EAAEV,CAAC,CAACO,MAAM,CAAC,CAAC;IACfI,GAAG,EAAEX,CAAC,CAACO,MAAM,CAAC,CAAC;IACfK,GAAG,EAAEZ,CAAC,CAACa,MAAM,CAAC,CAAC;IACfC,GAAG,EAAEd,CAAC,CAACa,MAAM,CAAC,CAAC;IACfU,SAAS,EAAEvB,CAAC,CAACO,MAAM,CAAC,CAAC;IACrBiB,cAAc,EAAExB,CAAC,CAACO,MAAM,CAAC,CAAC;IAC1BkB,GAAG,EAAEzB,CAAC,CAACO,MAAM,CAAC,CAAC,CAACmB,QAAQ,CAAC,CAAC;IAC1BN,GAAG,EAAEpB,CAAC,CAACO,MAAM,CAAC,CAAC;IACfc,GAAG,EAAErB,CAAC,CAACK,OAAO,CAAC,MAAM;EACvB,CAAC;AACH,CAAC,CAAC;AAiBF,OAAO,MAAMsB,yBAAyB,GAAG3B,CAAC,CAACE,MAAM,CAAC;EAChDa,MAAM,EAAEf,CAAC,CAACK,OAAO,CAAC,qBAAqB,CAAC;EACxCW,IAAI,EAAEhB,CAAC,CAACK,OAAO,CAAC,iBAAiB,CAAC;EAClCuB,kBAAkB,EAAE5B,CAAC,CAACO,MAAM,CAAC,CAAC;EAC9BsB,YAAY,EAAE7B,CAAC,CAACO,MAAM,CAAC;AACzB,CAAC,CAAC"}

package/lib/module/credential/offer/01-start-flow.js

@@ -0,0 +1,66 @@
+import * as z from "zod";
+import { Logger, LogLevel } from "../../utils/logging";
+import { stringToJSONSchema } from "../../utils/zod";
+import { InvalidQRCodeError } from "./errors";
+import { CredentialOfferSchema } from "./types";
+const CREDENTIAL_OFFER_SCHEMES = ["openid-credential-offer://", "haip://"];
+const CREDENTIAL_OFFER_PARAM = "credential_offer";
+const CREDENTIAL_OFFER_URI_PARAM = "credential_offer_uri";
+const CredentialOfferParams = z.union([z.object({
+  credential_offer: stringToJSONSchema.pipe(CredentialOfferSchema),
+  credential_offer_uri: z.undefined()
+}), z.object({
+  credential_offer: z.undefined(),
+  credential_offer_uri: z.string().url()
+})]);
+
+/**
+ * The beginning of the credential offer flow.
+ * To be implemented according to the user touchpoint
+ *
+ * @param params Credential offer encoded url
+ * @returns Object containing the credential offer by reference or by value
+ */
+
+/**
+ * Start a credential offer flow by validating and parse an encoded url
+ * extracted from a QR code or a deep link.
+ *
+ * @param params The encoded url to be validated and parsed
+ * @returns Object containing the credential offer by reference or by value
+ * @throws If the provided encoded url is not valid
+ */
+export const startFlowFromQR = encodedUrl => {
+  const hasValidScheme = CREDENTIAL_OFFER_SCHEMES.some(prefix => encodedUrl.startsWith(prefix));
+  if (!hasValidScheme) {
+    throw new InvalidQRCodeError("Url must have one of the supported schemes");
+  }
+  const url = new URL(encodedUrl);
+  const offerParam = url.searchParams.get(CREDENTIAL_OFFER_PARAM);
+  const offerUriParam = url.searchParams.get(CREDENTIAL_OFFER_URI_PARAM);
+  if (offerParam) {
+    const decoded = decodeURIComponent(offerParam);
+    const result = CredentialOfferParams.safeParse({
+      credential_offer: decoded
+    });
+    if (result.success) {
+      return result.data;
+    }
+    Logger.log(LogLevel.ERROR, `Invalid credential offer object found in QR Code: ${result.error.message}`);
+    throw new InvalidQRCodeError(result.error.message);
+  }
+  if (offerUriParam) {
+    const decoded = decodeURIComponent(offerUriParam);
+    const result = CredentialOfferParams.safeParse({
+      credential_offer_uri: decoded
+    });
+    if (result.success) {
+      return result.data;
+    }
+    Logger.log(LogLevel.ERROR, `Invalid credential offer URI found in QR Code: ${result.error.message}`);
+    throw new InvalidQRCodeError(result.error.message);
+  }
+  Logger.log(LogLevel.ERROR, `Invalid credential offer QR Code:`);
+  throw new InvalidQRCodeError("QR Code does not contain valid params");
+};
+//# sourceMappingURL=01-start-flow.js.map

package/lib/module/credential/offer/01-start-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["z","Logger","LogLevel","stringToJSONSchema","InvalidQRCodeError","CredentialOfferSchema","CREDENTIAL_OFFER_SCHEMES","CREDENTIAL_OFFER_PARAM","CREDENTIAL_OFFER_URI_PARAM","CredentialOfferParams","union","object","credential_offer","pipe","credential_offer_uri","undefined","string","url","startFlowFromQR","encodedUrl","hasValidScheme","some","prefix","startsWith","URL","offerParam","searchParams","get","offerUriParam","decoded","decodeURIComponent","result","safeParse","success","data","log","ERROR","error","message"],"sourceRoot":"../../../../src","sources":["credential/offer/01-start-flow.ts"],"mappings":"AAAA,OAAO,KAAKA,CAAC,MAAM,KAAK;AACxB,SAASC,MAAM,EAAEC,QAAQ,QAAQ,qBAAqB;AACtD,SAASC,kBAAkB,QAAQ,iBAAiB;AACpD,SAASC,kBAAkB,QAAQ,UAAU;AAC7C,SAASC,qBAAqB,QAAQ,SAAS;AAE/C,MAAMC,wBAAwB,GAAG,CAAC,4BAA4B,EAAE,SAAS,CAAC;AAC1E,MAAMC,sBAAsB,GAAG,kBAAkB;AACjD,MAAMC,0BAA0B,GAAG,sBAAsB;AAEzD,MAAMC,qBAAqB,GAAGT,CAAC,CAACU,KAAK,CAAC,CACpCV,CAAC,CAACW,MAAM,CAAC;EACPC,gBAAgB,EAAET,kBAAkB,CAACU,IAAI,CAACR,qBAAqB,CAAC;EAChES,oBAAoB,EAAEd,CAAC,CAACe,SAAS,CAAC;AACpC,CAAC,CAAC,EACFf,CAAC,CAACW,MAAM,CAAC;EACPC,gBAAgB,EAAEZ,CAAC,CAACe,SAAS,CAAC,CAAC;EAC/BD,oBAAoB,EAAEd,CAAC,CAACgB,MAAM,CAAC,CAAC,CAACC,GAAG,CAAC;AACvC,CAAC,CAAC,CACH,CAAC;;AAGF;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAA0B,GAAIC,UAAU,IAAK;EACxD,MAAMC,cAAc,GAAGd,wBAAwB,CAACe,IAAI,CAAEC,MAAM,IAC1DH,UAAU,CAACI,UAAU,CAACD,MAAM,CAC9B,CAAC;EAED,IAAI,CAACF,cAAc,EAAE;IACnB,MAAM,IAAIhB,kBAAkB,CAAC,4CAA4C,CAAC;EAC5E;EAEA,MAAMa,GAAG,GAAG,IAAIO,GAAG,CAACL,UAAU,CAAC;EAC/B,MAAMM,UAAU,GAAGR,GAAG,CAACS,YAAY,CAACC,GAAG,CAACpB,sBAAsB,CAAC;EAC/D,MAAMqB,aAAa,GAAGX,GAAG,CAACS,YAAY,CAACC,GAAG,CAACnB,0BAA0B,CAAC;EAEtE,IAAIiB,UAAU,EAAE;IACd,MAAMI,OAAO,GAAGC,kBAAkB,CAACL,UAAU,CAAC;IAC9C,MAAMM,MAAM,GAAGtB,qBAAqB,CAACuB,SAAS,CAAC;MAC7CpB,gBAAgB,EAAEiB;IACpB,CAAC,CAAC;IAEF,IAAIE,MAAM,CAACE,OAAO,EAAE;MAClB,OAAOF,MAAM,CAACG,IAAI;IACpB;IAEAjC,MAAM,CAACkC,GAAG,CACRjC,QAAQ,CAACkC,KAAK,EACb,qDAAoDL,MAAM,CAACM,KAAK,CAACC,OAAQ,EAC5E,CAAC;IACD,MAAM,IAAIlC,kBAAkB,CAAC2B,MAAM,CAACM,KAAK,CAACC,OAAO,CAAC;EACpD;EAEA,IAAIV,aAAa,EAAE;IACjB,MAAMC,OAAO,GAAGC,kBAAkB,CAACF,aAAa,CAAC;IACjD,MAAMG,MAAM,GAAGtB,qBAAqB,CAACuB,SAAS,CAAC;MAC7ClB,oBAAoB,EAAEe;IACxB,CAAC,CAAC;IAEF,IAAIE,MAAM,CAACE,OAAO,EAAE;MAClB,OAAOF,MAAM,CAACG,IAAI;IACpB;IAEAjC,MAAM,CAACkC,GAAG,CACRjC,QAAQ,CAACkC,KAAK,EACb,kDAAiDL,MAAM,CAACM,KAAK,CAACC,OAAQ,EACzE,CAAC;IACD,MAAM,IAAIlC,kBAAkB,CAAC2B,MAAM,CAACM,KAAK,CAACC,OAAO,CAAC;EACpD;EAEArC,MAAM,CAACkC,GAAG,CAACjC,QAAQ,CAACkC,KAAK,EAAG,mCAAkC,CAAC;EAC/D,MAAM,IAAIhC,kBAAkB,CAAC,uCAAuC,CAAC;AACvE,CAAC"}

package/lib/module/credential/offer/02-fetch-credential-offer.js

@@ -0,0 +1,38 @@
+import { IssuerResponseError } from "../../utils/errors";
+import { Logger, LogLevel } from "../../utils/logging";
+import { hasStatusOrThrow } from "../../utils/misc";
+import { InvalidCredentialOfferError } from "./errors";
+import { CredentialOfferSchema } from "./types";
+/**
+ * Fetches and validates a credential offer from a given URI.
+ *
+ * This function performs an HTTP GET request to the specified `credentialOfferUri`,
+ * expecting a JSON response that matches the `CredentialOfferSchema`. If the response
+ * is invalid or does not conform to the schema, an error is logged and an
+ * `InvalidCredentialOfferError` is thrown.
+ *
+ * @param credentialOfferUri - The URI from which to fetch the credential offer.
+ * @param context - Optional context object that may provide a custom `appFetch` implementation.
+ * @returns The validated credential offer data.
+ * @throws {IssuerResponseError} If the HTTP response status is not 200.
+ * @throws {InvalidCredentialOfferError} If the response does not match the expected schema.
+ */
+export const fetchCredentialOffer = async function (uri) {
+  let context = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  const {
+    appFetch = fetch
+  } = context;
+  const response = await appFetch(uri, {
+    method: "GET",
+    headers: {
+      Accept: "application/json"
+    }
+  }).then(hasStatusOrThrow(200, IssuerResponseError)).then(reqUri => reqUri.json());
+  const credentialOffer = CredentialOfferSchema.safeParse(response);
+  if (!credentialOffer.success) {
+    Logger.log(LogLevel.ERROR, `Invalid credential offer fetched from URI: ${uri} - ${credentialOffer.error.message}`);
+    throw new InvalidCredentialOfferError(`Invalid credential offer fetched from URI: ${uri} - ${credentialOffer.error.message}`);
+  }
+  return credentialOffer.data;
+};
+//# sourceMappingURL=02-fetch-credential-offer.js.map

package/lib/module/credential/offer/02-fetch-credential-offer.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["IssuerResponseError","Logger","LogLevel","hasStatusOrThrow","InvalidCredentialOfferError","CredentialOfferSchema","fetchCredentialOffer","uri","context","arguments","length","undefined","appFetch","fetch","response","method","headers","Accept","then","reqUri","json","credentialOffer","safeParse","success","log","ERROR","error","message","data"],"sourceRoot":"../../../../src","sources":["credential/offer/02-fetch-credential-offer.ts"],"mappings":"AAAA,SAASA,mBAAmB,QAAQ,oBAAoB;AACxD,SAASC,MAAM,EAAEC,QAAQ,QAAQ,qBAAqB;AACtD,SAASC,gBAAgB,QAAQ,kBAAkB;AACnD,SAASC,2BAA2B,QAAQ,UAAU;AAEtD,SAASC,qBAAqB,QAAQ,SAAS;AAS/C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,oBAAwC,GAAG,eAAAA,CACtDC,GAAW,EAER;EAAA,IADHC,OAAO,GAAAC,SAAA,CAAAC,MAAA,QAAAD,SAAA,QAAAE,SAAA,GAAAF,SAAA,MAAG,CAAC,CAAC;EAEZ,MAAM;IAAEG,QAAQ,GAAGC;EAAM,CAAC,GAAGL,OAAO;EAEpC,MAAMM,QAAQ,GAAG,MAAMF,QAAQ,CAACL,GAAG,EAAE;IACnCQ,MAAM,EAAE,KAAK;IACbC,OAAO,EAAE;MAAEC,MAAM,EAAE;IAAmB;EACxC,CAAC,CAAC,CACCC,IAAI,CAACf,gBAAgB,CAAC,GAAG,EAAEH,mBAAmB,CAAC,CAAC,CAChDkB,IAAI,CAAEC,MAAM,IAAKA,MAAM,CAACC,IAAI,CAAC,CAAC,CAAC;EAElC,MAAMC,eAAe,GAAGhB,qBAAqB,CAACiB,SAAS,CAACR,QAAQ,CAAC;EACjE,IAAI,CAACO,eAAe,CAACE,OAAO,EAAE;IAC5BtB,MAAM,CAACuB,GAAG,CACRtB,QAAQ,CAACuB,KAAK,EACb,8CAA6ClB,GAAI,MAAKc,eAAe,CAACK,KAAK,CAACC,OAAQ,EACvF,CAAC;IACD,MAAM,IAAIvB,2BAA2B,CAClC,8CAA6CG,GAAI,MAAKc,eAAe,CAACK,KAAK,CAACC,OAAQ,EACvF,CAAC;EACH;EAEA,OAAON,eAAe,CAACO,IAAI;AAC7B,CAAC"}

package/lib/module/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/lib/module/credential/offer/errors.js

@@ -0,0 +1,14 @@
+import { IoWalletError } from "../../utils/errors";
+export class InvalidCredentialOfferError extends IoWalletError {
+  code = "ERR_INVALID_CREDENTIAL_OFFER";
+  constructor(message) {
+    super(message);
+  }
+}
+export class InvalidQRCodeError extends IoWalletError {
+  code = "ERR_INVALID_QR_CODE";
+  constructor(message) {
+    super(message);
+  }
+}
+//# sourceMappingURL=errors.js.map

package/lib/module/credential/offer/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["IoWalletError","InvalidCredentialOfferError","code","constructor","message","InvalidQRCodeError"],"sourceRoot":"../../../../src","sources":["credential/offer/errors.ts"],"mappings":"AAAA,SAASA,aAAa,QAAQ,oBAAoB;AAElD,OAAO,MAAMC,2BAA2B,SAASD,aAAa,CAAC;EAC7DE,IAAI,GAAG,8BAA8B;EAErCC,WAAWA,CAACC,OAAgB,EAAE;IAC5B,KAAK,CAACA,OAAO,CAAC;EAChB;AACF;AAEA,OAAO,MAAMC,kBAAkB,SAASL,aAAa,CAAC;EACpDE,IAAI,GAAG,qBAAqB;EAE5BC,WAAWA,CAACC,OAAgB,EAAE;IAC5B,KAAK,CAACA,OAAO,CAAC;EAChB;AACF"}

package/lib/module/credential/offer/index.js

@@ -0,0 +1,5 @@
+import { startFlowFromQR } from "./01-start-flow";
+import { fetchCredentialOffer } from "./02-fetch-credential-offer";
+import * as Errors from "./errors";
+export { Errors, fetchCredentialOffer, startFlowFromQR };
+//# sourceMappingURL=index.js.map

package/lib/module/credential/offer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["startFlowFromQR","fetchCredentialOffer","Errors"],"sourceRoot":"../../../../src","sources":["credential/offer/index.ts"],"mappings":"AAAA,SAASA,eAAe,QAAwB,iBAAiB;AACjE,SACEC,oBAAoB,QAEf,6BAA6B;AACpC,OAAO,KAAKC,MAAM,MAAM,UAAU;AASlC,SAASA,MAAM,EAAED,oBAAoB,EAAED,eAAe"}

package/lib/module/credential/offer/types.js

@@ -0,0 +1,41 @@
+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()
+});
+/**
+ * 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()
+});
+/**
+ * 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()
+});
+/**
+ * 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()
+});
+/**
+ * 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()
+});
+//# sourceMappingURL=types.js.map

package/lib/module/credential/offer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["z","AuthorizationCodeGrantSchema","object","issuer_state","string","optional","authorization_server","url","TransactionCodeSchema","input_mode","enum","length","number","int","positive","description","max","PreAuthorizedCodeGrantSchema","tx_code","GrantsSchema","authorization_code","CredentialOfferSchema","credential_issuer","credential_configuration_ids","array","min","grants"],"sourceRoot":"../../../../src","sources":["credential/offer/types.ts"],"mappings":"AAAA,SAASA,CAAC,QAAQ,KAAK;;AAEvB;AACA;AACA;AACA,OAAO,MAAMC,4BAA4B,GAAGD,CAAC,CAACE,MAAM,CAAC;EACnDC,YAAY,EAAEH,CAAC,CAACI,MAAM,CAAC,CAAC,CAACC,QAAQ,CAAC,CAAC;EACnCC,oBAAoB,EAAEN,CAAC,CAACI,MAAM,CAAC,CAAC,CAACG,GAAG,CAAC,CAAC,CAACF,QAAQ,CAAC;AAClD,CAAC,CAAC;AAMF;AACA;AACA;AACA,OAAO,MAAMG,qBAAqB,GAAGR,CAAC,CAACE,MAAM,CAAC;EAC5CO,UAAU,EAAET,CAAC,CAACU,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAACL,QAAQ,CAAC,CAAC;EAClDM,MAAM,EAAEX,CAAC,CAACY,MAAM,CAAC,CAAC,CAACC,GAAG,CAAC,CAAC,CAACC,QAAQ,CAAC,CAAC,CAACT,QAAQ,CAAC,CAAC;EAC9CU,WAAW,EAAEf,CAAC,CAACI,MAAM,CAAC,CAAC,CAACY,GAAG,CAAC,GAAG,CAAC,CAACX,QAAQ,CAAC;AAC5C,CAAC,CAAC;AAIF;AACA;AACA;AACA,OAAO,MAAMY,4BAA4B,GAAGjB,CAAC,CAACE,MAAM,CAAC;EACnD,qBAAqB,EAAEF,CAAC,CAACI,MAAM,CAAC,CAAC;EACjCc,OAAO,EAAEV,qBAAqB,CAACH,QAAQ,CAAC,CAAC;EACzCC,oBAAoB,EAAEN,CAAC,CAACI,MAAM,CAAC,CAAC,CAACG,GAAG,CAAC,CAAC,CAACF,QAAQ,CAAC;AAClD,CAAC,CAAC;AAMF;AACA;AACA;AACA,OAAO,MAAMc,YAAY,GAAGnB,CAAC,CAACE,MAAM,CAAC;EACnCkB,kBAAkB,EAAEnB,4BAA4B,CAACI,QAAQ,CAAC,CAAC;EAC3D,sDAAsD,EACpDY,4BAA4B,CAACZ,QAAQ,CAAC;AAC1C,CAAC,CAAC;AAIF;AACA;AACA;AACA,OAAO,MAAMgB,qBAAqB,GAAGrB,CAAC,CAACE,MAAM,CAAC;EAC5CoB,iBAAiB,EAAEtB,CAAC,CAACI,MAAM,CAAC,CAAC,CAACG,GAAG,CAAC,CAAC;EACnCgB,4BAA4B,EAAEvB,CAAC,CAACwB,KAAK,CAACxB,CAAC,CAACI,MAAM,CAAC,CAAC,CAAC,CAACqB,GAAG,CAAC,CAAC,CAAC;EACxDC,MAAM,EAAEP,YAAY,CAACd,QAAQ,CAAC;AAChC,CAAC,CAAC"}

package/lib/module/credential/presentation/01-start-flow.js

@@ -9,7 +9,7 @@ const PresentationParams = z.object({
 
 /**
  * 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/lib/module/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);
+```