@pagopa/io-react-native-wallet 2.0.0-next.0 → 2.0.0-next.1

package/lib/typescript/trust/utils.d.ts

@@ -1,4 +1,5 @@
 import type { JWK, JWTDecodeResult } from "../utils/jwk";
+import type { TrustAnchorEntityConfiguration } from "./types";
 export type ParsedToken = {
     header: JWTDecodeResult["protectedHeader"];
     payload: JWTDecodeResult["payload"];
@@ -9,4 +10,13 @@ export declare const verify: (token: string, kid: string, jwks: JWK[]) => Promis
  * It seems like typescript can't correctly infer the return type of the function.
  */
 export declare const decode: (token: string) => ParsedToken;
+/**
+ * Extracts the X.509 Trust Anchor certificate (Base64 encoded) from the
+ * Trust Anchor's Entity Configuration.
+ *
+ * @param trustAnchorEntity The entity configuration of the known trust anchor.
+ * @returns The Base64 encoded X.509 certificate string.
+ * @throws {FederationError} If the certificate cannot be derived.
+ */
+export declare function getTrustAnchorX509Certificate(trustAnchorEntity: TrustAnchorEntityConfiguration): string;
 //# sourceMappingURL=utils.d.ts.map

package/lib/typescript/trust/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/trust/utils.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;IAC3C,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;CACrC,CAAC;AAIF,eAAO,MAAM,MAAM,UACV,MAAM,OACR,MAAM,QACL,GAAG,EAAE,KACV,QAAQ,WAAW,CAOrB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,MAAM,UAAW,MAAM,KAAG,WAGtC,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/trust/utils.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,SAAS,CAAC;AAE9D,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;IAC3C,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;CACrC,CAAC;AAIF,eAAO,MAAM,MAAM,UACV,MAAM,OACR,MAAM,QACL,GAAG,EAAE,KACV,QAAQ,WAAW,CAOrB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,MAAM,UAAW,MAAM,KAAG,WAGtC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,iBAAiB,EAAE,8BAA8B,GAChD,MAAM,CAqBR"}

package/lib/typescript/wallet-instance-attestation/types.d.ts

@@ -246,6 +246,15 @@ export declare const WalletInstanceAttestationRequestJwt: z.ZodObject<{
         integrity_assertion: string;
     }>>;
 }, "strip", z.ZodTypeAny, {
+    header: {
+        alg: string;
+        kid: string;
+        typ: string;
+        x5c?: string[] | undefined;
+        trust_chain?: string[] | undefined;
+    } & {
+        typ: "wp-war+jwt";
+    };
     payload: {
         iss: string;
         iat: number;
@@ -285,6 +294,7 @@ export declare const WalletInstanceAttestationRequestJwt: z.ZodObject<{
         hardware_signature: string;
         integrity_assertion: string;
     };
+}, {
     header: {
         alg: string;
         kid: string;
@@ -294,7 +304,6 @@ export declare const WalletInstanceAttestationRequestJwt: z.ZodObject<{
     } & {
         typ: "wp-war+jwt";
     };
-}, {
     payload: {
         iss: string;
         iat: number;
@@ -334,15 +343,6 @@ export declare const WalletInstanceAttestationRequestJwt: z.ZodObject<{
         hardware_signature: string;
         integrity_assertion: string;
     };
-    header: {
-        alg: string;
-        kid: string;
-        typ: string;
-        x5c?: string[] | undefined;
-        trust_chain?: string[] | undefined;
-    } & {
-        typ: "wp-war+jwt";
-    };
 }>;
 export type WalletInstanceAttestationJwt = z.infer<typeof WalletInstanceAttestationJwt>;
 export declare const WalletInstanceAttestationJwt: z.ZodObject<{
@@ -591,6 +591,16 @@ export declare const WalletInstanceAttestationJwt: z.ZodObject<{
         wallet_name?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
+    header: {
+        alg: string;
+        kid: string;
+        typ: string;
+        x5c?: string[] | undefined;
+        trust_chain?: string[] | undefined;
+    } & {
+        typ: "oauth-client-attestation+jwt";
+        trust_chain: string[];
+    };
     payload: {
         iss: string;
         iat: number;
@@ -629,6 +639,7 @@ export declare const WalletInstanceAttestationJwt: z.ZodObject<{
         wallet_link?: string | undefined;
         wallet_name?: string | undefined;
     };
+}, {
     header: {
         alg: string;
         kid: string;
@@ -639,7 +650,6 @@ export declare const WalletInstanceAttestationJwt: z.ZodObject<{
         typ: "oauth-client-attestation+jwt";
         trust_chain: string[];
     };
-}, {
     payload: {
         iss: string;
         iat: number;
@@ -678,16 +688,6 @@ export declare const WalletInstanceAttestationJwt: z.ZodObject<{
         wallet_link?: string | undefined;
         wallet_name?: string | undefined;
     };
-    header: {
-        alg: string;
-        kid: string;
-        typ: string;
-        x5c?: string[] | undefined;
-        trust_chain?: string[] | undefined;
-    } & {
-        typ: "oauth-client-attestation+jwt";
-        trust_chain: string[];
-    };
 }>;
 export type WalletAttestationResponse = z.infer<typeof WalletAttestationResponse>;
 export declare const WalletAttestationResponse: z.ZodObject<{
@@ -695,21 +695,21 @@ export declare const WalletAttestationResponse: z.ZodObject<{
         wallet_attestation: z.ZodString;
         format: z.ZodEnum<["jwt", "dc+sd-jwt", "mso_mdoc"]>;
     }, "strip", z.ZodTypeAny, {
-        format: "jwt" | "dc+sd-jwt" | "mso_mdoc";
         wallet_attestation: string;
-    }, {
         format: "jwt" | "dc+sd-jwt" | "mso_mdoc";
+    }, {
         wallet_attestation: string;
+        format: "jwt" | "dc+sd-jwt" | "mso_mdoc";
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     wallet_attestations: {
-        format: "jwt" | "dc+sd-jwt" | "mso_mdoc";
         wallet_attestation: string;
+        format: "jwt" | "dc+sd-jwt" | "mso_mdoc";
     }[];
 }, {
     wallet_attestations: {
-        format: "jwt" | "dc+sd-jwt" | "mso_mdoc";
         wallet_attestation: string;
+        format: "jwt" | "dc+sd-jwt" | "mso_mdoc";
     }[];
 }>;
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagopa/io-react-native-wallet",
-  "version": "2.0.0-next.0",
+  "version": "2.0.0-next.1",
   "description": "Provide data structures, helpers and API for IO Wallet",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -53,7 +53,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@pagopa/io-react-native-crypto": "^0.2.3",
+    "@pagopa/io-react-native-crypto": "^1.2.2",
     "@pagopa/io-react-native-jwt": "^2.1.0",
     "@react-native/eslint-config": "^0.75.5",
     "@rushstack/eslint-patch": "^1.3.2",

package/src/trust/README.md

@@ -0,0 +1,147 @@
+# Trust Chain Validation
+
+This module implements **Trust Chain validation** for Entity Configurations and Entity Statements in line with the [IT Wallet Federation Specifications](https://italia.github.io/eid-wallet-it-docs/). It ensures that an entity's metadata is trusted by validating a chain of signed JWTs up to a known Trust Anchor.
+
+The validation covers:
+
+* JWT signature verification (using the next entity's JWKS)
+* Trust chain ordering (leaf → parent → Trust Anchor)
+* Optional X.509 CRL-based certificate validation
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant A as Leaf Entity
+  participant B as Intermediate (Federation Authority)
+  participant C as Trust Anchor
+
+  A->>A: Self-issued Entity Configuration (JWT)
+  B->>A: Signed Entity Statement (JWT)
+  C->>B: Signed Entity Statement (JWT or self-issued EC)
+
+  Note over A,C: Each JWT is validated with the next issuer's public keys
+```
+
+## Errors
+
+| Error                         | Description                                                        |
+| ----------------------------- | ------------------------------------------------------------------ |
+| `TrustChainEmptyError`        | The input chain is empty.                                          |
+| `TrustChainTokenMissingError` | One of the JWTs in the chain is missing.                           |
+| `X509ValidationError`         | X.509 certificate validation failed (e.g. revocation, expiration). |
+| `FederationError`             | Generic federation processing error.                               |
+
+## Usage
+
+### Validate a trust chain
+
+```ts
+import { validateTrustChain } from "./trust";
+import { trustAnchorEntityConfiguration } from "./your-data";
+import { chain } from "./your-data"; // array of JWTs, starting from leaf
+
+const result = await validateTrustChain(trustAnchorEntityConfiguration, chain, {
+    connectTimeout: 3000,
+    readTimeout: 3000,
+    requireCrl: false,
+});
+```
+
+* The `chain` must be an array of signed JWT strings.
+* The first JWT must be a self-issued `EntityConfiguration`.
+* The last JWT must be an `EntityStatement` or a self-issued Trust Anchor `EntityConfiguration`.
+
+### Renew a trust chain
+
+```ts
+import { renewTrustChain } from "./trust";
+
+const newChain = await renewTrustChain(chain);
+```
+
+This will fetch updated JWTs from each authority in the chain.
+
+### Build a trust chain
+
+```ts
+import { buildTrustChain } from "./trust";
+
+const chain = await buildTrustChain({
+  leaf: "https://example-leaf",
+  trustAnchor: trustAnchorEntityConfiguration,
+});
+```
+
+* **leaf**: the entity URL of the subject to be trusted.
+* **trustAnchor**: the known trust anchor configuration.
+* Returns a list of JWT strings ordered from leaf to trust anchor.
+
+
+## Trust Chain Structure
+
+| Position | JWT Type                            | Requirements                  |
+| -------- | ----------------------------------- |-------------------------------|
+| First    | Entity Configuration                | `iss === sub` (self-issued)   |
+| Middle   | Entity Statement                    | `iss ≠ sub`, signed by parent |
+| Last     | Entity Statement or Trust Anchor EC | Trust Anchor must be known    |
+
+### Build and Validate Example
+
+```ts
+import {
+  buildTrustChain,
+  validateTrustChain,
+} from "./trust";
+import { trustAnchorEntityConfiguration } from "./your-data";
+
+const chain = await buildTrustChain({
+  leaf: "https://example-leaf",
+  trustAnchor: trustAnchorEntityConfiguration,
+});
+
+const result = await validateTrustChain(trustAnchorEntityConfiguration, chain, {
+  connectTimeout: 3000,
+  readTimeout: 3000,
+  requireCrl: true,
+});
+```
+
+* This example fetches and builds the full trust chain dynamically, then validates it end-to-end.
+
+## Example Trust Chain
+
+```ts
+[
+    {
+        header: { alg: "ES256", kid: "leaf-kid" },
+        payload: { iss: "https://leaf", sub: "https://leaf", jwks: { keys: [...] } }
+    },
+    {
+        header: { alg: "ES256", kid: "intermediate-kid" },
+        payload: { iss: "https://intermediate", sub: "https://leaf", jwks: { keys: [...] } }
+    },
+    {
+        header: { alg: "ES256", kid: "ta-kid" },
+        payload: { iss: "https://ta", sub: "https://ta", jwks: { keys: [...] } }
+    }
+]
+```
+
+## Mocking in Tests
+
+If you're testing in Node (not in React Native), you need to mock X.509 and crypto-native dependencies:
+
+```ts
+jest.mock("@pagopa/io-react-native-crypto", () => ({
+    verifyCertificateChain: jest.fn().mockResolvedValue({
+        isValid: true,
+        validationStatus: "VALID",
+        errorMessage: undefined,
+    }),
+    generate: jest.fn().mockResolvedValue({ ... }),
+}));
+```
+
+Ensure mocked `JWK`s contain an `x5c` array to trigger certificate validation logic during tests.

package/src/trust/chain.ts

@@ -6,13 +6,26 @@ import {
 import { JWK } from "../utils/jwk";
 import * as z from "zod";
 import { getSignedEntityConfiguration, getSignedEntityStatement } from ".";
-import { decode, type ParsedToken, verify } from "./utils";
 import {
+  decode,
+  getTrustAnchorX509Certificate,
+  type ParsedToken,
+  verify,
+} from "./utils";
+import {
+  FederationError,
   MissingFederationFetchEndpointError,
+  MissingX509CertsError,
   TrustChainEmptyError,
   TrustChainRenewalError,
   TrustChainTokenMissingError,
+  X509ValidationError,
 } from "./errors";
+import {
+  type CertificateValidationResult,
+  verifyCertificateChain,
+  type X509CertificateOptions,
+} from "@pagopa/io-react-native-crypto";
 
 // The first element of the chain is supposed to be the Entity Configuration for the document issuer
 const FirstElementShape = EntityConfiguration;
@@ -26,16 +39,18 @@ const LastElementShape = z.union([
 ]);
 
 /**
- * Validates a provided trust chain against a known trust
+ * Validates a provided trust chain against a known trust anchor, including X.509 certificate checks.
  *
- * @param trustAnchorEntity The entity configuration of the known trust anchor
- * @param chain The chain of statements to be validated
- * @returns The list of parsed token representing the chain
- * @throws {FederationError} If the chain is not valid
+ * @param trustAnchorEntity The entity configuration of the known trust anchor (for JWT validation).
+ * @param chain The chain of statements to be validated.
+ * @param x509Options Options for X.509 certificate validation.
+ * @returns The list of parsed tokens representing the chain.
+ * @throws {FederationError} If the chain is not valid (JWT or X.509). Specific errors like TrustChainEmptyError, X509ValidationError may be thrown.
  */
 export async function validateTrustChain(
   trustAnchorEntity: TrustAnchorEntityConfiguration,
-  chain: string[]
+  chain: string[],
+  x509Options: X509CertificateOptions
 ): Promise<ParsedToken[]> {
   // If the chain is empty, fail
   if (chain.length === 0) {
@@ -50,7 +65,7 @@ export async function validateTrustChain(
         ? LastElementShape
         : MiddleElementShape;
 
-  // select the kid from the current index
+  // Select the kid from the current index
   const selectKid = (currentIndex: number): string => {
     const token = chain[currentIndex];
     if (!token) {
@@ -63,8 +78,8 @@ export async function validateTrustChain(
     return shape.parse(decode(token)).header.kid;
   };
 
-  // select keys from the next token
-  // if the current token is the last, keys from trust anchor will be used
+  // Select keys from the next token
+  // If the current token is the last, keys from trust anchor will be used
   const selectKeys = (currentIndex: number): JWK[] => {
     if (currentIndex === chain.length - 1) {
       return trustAnchorEntity.payload.jwks.keys;
@@ -82,13 +97,74 @@ export async function validateTrustChain(
     return shape.parse(decode(nextToken)).payload.jwks.keys;
   };
 
+  const x509TrustAnchorCertBase64 =
+    getTrustAnchorX509Certificate(trustAnchorEntity);
+
   // Iterate the chain and validate each element's signature against the public keys of its next
   // If there is no next, hence it's the end of the chain, and it must be verified by the Trust Anchor
-  return Promise.all(
-    chain
-      .map((token, i) => [token, selectKid(i), selectKeys(i)] as const)
-      .map((args) => verify(...args))
-  );
+  const validationPromises = chain.map(async (tokenString, i) => {
+    const kidFromTokenHeader = selectKid(i);
+    const signerJwks = selectKeys(i);
+
+    // Step 1: Verify JWT signature
+    const parsedToken = await verify(
+      tokenString,
+      kidFromTokenHeader,
+      signerJwks
+    );
+
+    // Step 2: X.509 Certificate Chain Validation
+    const jwkUsedForVerification = signerJwks.find(
+      (k) => k.kid === kidFromTokenHeader
+    );
+
+    if (!jwkUsedForVerification) {
+      throw new FederationError(
+        `JWK with kid '${kidFromTokenHeader}' was not found in signer's JWKS for token at index ${i}, though JWT verification passed.`,
+        { tokenIndex: i, kid: kidFromTokenHeader }
+      );
+    }
+
+    if (
+      !jwkUsedForVerification.x5c ||
+      jwkUsedForVerification.x5c.length === 0
+    ) {
+      throw new MissingX509CertsError(
+        `JWK with kid '${kidFromTokenHeader}' does not contain an X.509 certificate chain (x5c) for token at index ${i}.`
+      );
+    }
+
+    // If the chain has more than one certificate AND
+    // the last certificate in the x5c chain is the same as the trust anchor,
+    // remove the anchor from the chain being passed, as it's supplied separately.
+    const certChainBase64 =
+      jwkUsedForVerification.x5c.length > 1 &&
+      jwkUsedForVerification.x5c.at(-1) === x509TrustAnchorCertBase64
+        ? jwkUsedForVerification.x5c.slice(0, -1)
+        : jwkUsedForVerification.x5c;
+
+    const x509ValidationResult: CertificateValidationResult =
+      await verifyCertificateChain(
+        certChainBase64,
+        x509TrustAnchorCertBase64,
+        x509Options
+      );
+
+    if (!x509ValidationResult.isValid) {
+      throw new X509ValidationError(
+        `X.509 certificate chain validation failed for token at index ${i} (kid: ${kidFromTokenHeader}). Status: ${x509ValidationResult.validationStatus}. Error: ${x509ValidationResult.errorMessage}`,
+        {
+          tokenIndex: i,
+          kid: kidFromTokenHeader,
+          x509ValidationStatus: x509ValidationResult.validationStatus,
+          x509ErrorMessage: x509ValidationResult.errorMessage,
+        }
+      );
+    }
+    return parsedToken;
+  });
+
+  return Promise.all(validationPromises);
 }
 
 /**

package/src/trust/errors.ts

@@ -1,4 +1,5 @@
-import { IoWalletError, serializeAttrs } from "../utils/errors"; // Ensure this path is correct
+import { IoWalletError, serializeAttrs } from "../utils/errors";
+import type { CertificateValidationStatus } from "@pagopa/io-react-native-crypto"; // Ensure this path is correct
 
 /**
  * Base class for all federation-specific errors.
@@ -103,3 +104,33 @@ export class MissingFederationFetchEndpointError extends FederationError {
     super(message, details);
   }
 }
+
+/**
+ * Error thrown when the X.509 certificate chain is missing in an entity's configuration.
+ */
+export class MissingX509CertsError extends FederationError {
+  code = "ERR_FED_MISSING_X509_CERTS";
+  constructor(message: string) {
+    super(message, undefined);
+  }
+}
+
+/**
+ * Error thrown when an X.509 certificate validation fails.
+ * This is used to indicate issues with the certificate chain or signature verification.
+ */
+export class X509ValidationError extends FederationError {
+  code = "ERR_FED_X509_VALIDATION_FAILED";
+  constructor(
+    message: string,
+    details?: {
+      tokenIndex?: number;
+      kid?: string;
+      x509ValidationStatus?: CertificateValidationStatus;
+      x509ErrorMessage?: string;
+      [key: string]: unknown;
+    }
+  ) {
+    super(message, details);
+  }
+}

package/src/trust/index.ts

@@ -19,6 +19,7 @@ import {
   RelyingPartyNotAuthorizedError,
   TrustAnchorKidMissingError,
 } from "./errors";
+import type { X509CertificateOptions } from "@pagopa/io-react-native-crypto";
 
 export type {
   WalletProviderEntityConfiguration,
@@ -35,25 +36,31 @@ export type {
  *
  * @param trustAnchorEntity The entity configuration of the known trust anchor
  * @param chain The chain of statements to be validated
- * @param renewOnFail Whether to renew the provided chain if the validation fails at first. Default: true
- * @param appFetch Fetch api implementation. Default: the built-in implementation
+ * @param x509Options Options for the verification process
+ * @param appFetch (optional) fetch api implementation
+ * @param renewOnFail Whether to attempt to renew the trust chain if the initial validation fails
  * @returns The result of the chain validation
  * @throws {FederationError} If the chain is not valid
  */
 export async function verifyTrustChain(
   trustAnchorEntity: TrustAnchorEntityConfiguration,
   chain: string[],
+  x509Options: X509CertificateOptions = {
+    connectTimeout: 10000,
+    readTimeout: 10000,
+    requireCrl: true,
+  },
   {
     appFetch = fetch,
     renewOnFail = true,
   }: { appFetch?: GlobalFetch["fetch"]; renewOnFail?: boolean } = {}
 ): Promise<ReturnType<typeof validateTrustChain>> {
   try {
-    return validateTrustChain(trustAnchorEntity, chain);
+    return validateTrustChain(trustAnchorEntity, chain, x509Options);
   } catch (error) {
     if (renewOnFail) {
       const renewedChain = await renewTrustChain(chain, appFetch);
-      return validateTrustChain(trustAnchorEntity, renewedChain);
+      return validateTrustChain(trustAnchorEntity, renewedChain, x509Options);
     } else {
       throw error;
     }

package/src/trust/utils.ts

@@ -4,6 +4,8 @@ import {
 } from "@pagopa/io-react-native-jwt";
 
 import type { JWK, JWTDecodeResult } from "../utils/jwk";
+import { FederationError } from "./errors";
+import type { TrustAnchorEntityConfiguration } from "./types";
 
 export type ParsedToken = {
   header: JWTDecodeResult["protectedHeader"];
@@ -33,3 +35,36 @@ export const decode = (token: string): ParsedToken => {
   const { protectedHeader: header, payload } = decodeJwt(token);
   return { header, payload };
 };
+
+/**
+ * Extracts the X.509 Trust Anchor certificate (Base64 encoded) from the
+ * Trust Anchor's Entity Configuration.
+ *
+ * @param trustAnchorEntity The entity configuration of the known trust anchor.
+ * @returns The Base64 encoded X.509 certificate string.
+ * @throws {FederationError} If the certificate cannot be derived.
+ */
+export function getTrustAnchorX509Certificate(
+  trustAnchorEntity: TrustAnchorEntityConfiguration
+): string {
+  const taHeaderKid = trustAnchorEntity.header.kid;
+  const taSigningJwk = trustAnchorEntity.payload.jwks.keys.find(
+    (key) => key.kid === taHeaderKid
+  );
+
+  if (!taSigningJwk) {
+    throw new FederationError(
+      `Cannot derive X.509 Trust Anchor certificate: JWK with kid '${taHeaderKid}' not found in Trust Anchor's JWKS.`,
+      { trustAnchorKid: taHeaderKid, reason: "JWK not found for header kid" }
+    );
+  }
+
+  if (taSigningJwk.x5c && taSigningJwk.x5c.length > 0 && taSigningJwk.x5c[0]) {
+    return taSigningJwk.x5c[0];
+  }
+
+  throw new FederationError(
+    `Cannot derive X.509 Trust Anchor certificate: JWK with kid '${taHeaderKid}' does not contain a valid 'x5c' certificate array.`,
+    { trustAnchorKid: taHeaderKid, reason: "Missing or empty x5c in JWK" }
+  );
+}