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

package/lib/module/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/lib/module/trust/chain.js

@@ -0,0 +1,145 @@
+import { EntityConfiguration, EntityStatement, TrustAnchorEntityConfiguration } from "./types";
+import * as z from "zod";
+import { getSignedEntityConfiguration, getSignedEntityStatement } from ".";
+import { decode, getTrustAnchorX509Certificate, verify } from "./utils";
+import { FederationError, MissingFederationFetchEndpointError, MissingX509CertsError, TrustChainEmptyError, TrustChainRenewalError, TrustChainTokenMissingError, X509ValidationError } from "./errors";
+import { verifyCertificateChain } 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;
+// Each element but the first is supposed to be an Entity Statement
+const MiddleElementShape = EntityStatement;
+// The last element of the chain can either be an Entity Statement
+//  or the Entity Configuration for the known Trust Anchor
+const LastElementShape = z.union([EntityStatement, TrustAnchorEntityConfiguration]);
+
+/**
+ * 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 (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, chain, x509Options) {
+  // If the chain is empty, fail
+  if (chain.length === 0) {
+    throw new TrustChainEmptyError("Cannot verify empty trust chain.");
+  }
+
+  // Select the expected token shape
+  const selectTokenShape = elementIndex => elementIndex === 0 ? FirstElementShape : elementIndex === chain.length - 1 ? LastElementShape : MiddleElementShape;
+
+  // Select the kid from the current index
+  const selectKid = currentIndex => {
+    const token = chain[currentIndex];
+    if (!token) {
+      throw new TrustChainTokenMissingError(`Token missing at index ${currentIndex} in trust chain.`, {
+        index: currentIndex
+      });
+    }
+    const shape = selectTokenShape(currentIndex);
+    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
+  const selectKeys = currentIndex => {
+    if (currentIndex === chain.length - 1) {
+      return trustAnchorEntity.payload.jwks.keys;
+    }
+    const nextIndex = currentIndex + 1;
+    const nextToken = chain[nextIndex];
+    if (!nextToken) {
+      throw new TrustChainTokenMissingError(`Next token missing at index ${nextIndex} (needed for keys for token at ${currentIndex}).`, {
+        index: nextIndex
+      });
+    }
+    const shape = selectTokenShape(nextIndex);
+    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
+  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 = 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);
+}
+
+/**
+ * Given a trust chain, obtain a new trust chain by fetching each element's fresh version
+ *
+ * @param chain The original chain
+ * @param appFetch (optional) fetch api implementation
+ * @returns A list of signed token that represent the trust chain, in the same order of the provided chain
+ * @throws {FederationError} If the chain is not valid
+ */
+export async function renewTrustChain(chain) {
+  let appFetch = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : fetch;
+  return Promise.all(chain.map(async (token, index) => {
+    const decoded = decode(token);
+    const entityStatementResult = EntityStatement.safeParse(decoded);
+    const entityConfigurationResult = EntityConfiguration.safeParse(decoded);
+    if (entityConfigurationResult.success) {
+      return getSignedEntityConfiguration(entityConfigurationResult.data.payload.iss, {
+        appFetch
+      });
+    }
+    if (entityStatementResult.success) {
+      const entityStatement = entityStatementResult.data;
+      const parentBaseUrl = entityStatement.payload.iss;
+      const parentECJwt = await getSignedEntityConfiguration(parentBaseUrl, {
+        appFetch
+      });
+      const parentEC = EntityConfiguration.parse(decode(parentECJwt));
+      const federationFetchEndpoint = parentEC.payload.metadata.federation_entity.federation_fetch_endpoint;
+      if (!federationFetchEndpoint) {
+        throw new MissingFederationFetchEndpointError(`Parent EC at ${parentBaseUrl} is missing federation_fetch_endpoint, cannot renew ES for ${entityStatement.payload.sub}.`, {
+          entityBaseUrl: entityStatement.payload.sub,
+          missingInEntityUrl: parentBaseUrl
+        });
+      }
+      return getSignedEntityStatement(federationFetchEndpoint, entityStatement.payload.sub, {
+        appFetch
+      });
+    }
+    throw new TrustChainRenewalError(`Failed to renew trust chain. Reason: element #${index} failed to parse.`, {
+      originalChain: chain
+    });
+  }));
+}
+//# sourceMappingURL=chain.js.map

package/lib/module/trust/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["EntityConfiguration","EntityStatement","TrustAnchorEntityConfiguration","z","getSignedEntityConfiguration","getSignedEntityStatement","decode","getTrustAnchorX509Certificate","verify","FederationError","MissingFederationFetchEndpointError","MissingX509CertsError","TrustChainEmptyError","TrustChainRenewalError","TrustChainTokenMissingError","X509ValidationError","verifyCertificateChain","FirstElementShape","MiddleElementShape","LastElementShape","union","validateTrustChain","trustAnchorEntity","chain","x509Options","length","selectTokenShape","elementIndex","selectKid","currentIndex","token","index","shape","parse","header","kid","selectKeys","payload","jwks","keys","nextIndex","nextToken","x509TrustAnchorCertBase64","validationPromises","map","tokenString","i","kidFromTokenHeader","signerJwks","parsedToken","jwkUsedForVerification","find","k","tokenIndex","x5c","certChainBase64","at","slice","x509ValidationResult","isValid","validationStatus","errorMessage","x509ValidationStatus","x509ErrorMessage","Promise","all","renewTrustChain","appFetch","arguments","undefined","fetch","decoded","entityStatementResult","safeParse","entityConfigurationResult","success","data","iss","entityStatement","parentBaseUrl","parentECJwt","parentEC","federationFetchEndpoint","metadata","federation_entity","federation_fetch_endpoint","sub","entityBaseUrl","missingInEntityUrl","originalChain"],"sourceRoot":"../../../src","sources":["trust/chain.ts"],"mappings":"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"}

package/lib/module/trust/errors.js

@@ -0,0 +1,115 @@
+import { IoWalletError, serializeAttrs } from "../utils/errors";
+// Ensure this path is correct
+/**
+ * Base class for all federation-specific errors.
+ */
+export class FederationError extends IoWalletError {
+  constructor(message, details) {
+    super(details ? serializeAttrs({
+      message,
+      ...details
+    }) : message);
+    this.name = this.constructor.name;
+  }
+}
+
+/**
+ * Error thrown when a trust chain is unexpectedly empty.
+ */
+export class TrustChainEmptyError extends FederationError {
+  code = "ERR_FED_TRUST_CHAIN_EMPTY";
+  constructor() {
+    let message = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "Trust chain cannot be empty.";
+    super(message, undefined);
+  }
+}
+
+/**
+ * Error thrown when a token is unexpectedly missing from a trust chain during processing.
+ */
+export class TrustChainTokenMissingError extends FederationError {
+  code = "ERR_FED_TRUST_CHAIN_TOKEN_MISSING";
+  constructor(message, details) {
+    super(message, details);
+  }
+}
+
+/**
+ * Error thrown when renewing a trust chain fails.
+ * This class itself might be used or could be considered a more general renewal error.
+ */
+export class TrustChainRenewalError extends FederationError {
+  code = "ERR_FED_TRUST_CHAIN_RENEWAL_FAILED";
+  constructor(message, details) {
+    super(message, details);
+  }
+}
+export class FederationListParseError extends FederationError {
+  code = "ERR_FED_FEDERATION_LIST_PARSE_FAILED";
+  constructor(message, details) {
+    super(message, details);
+  }
+}
+
+/**
+ * General error thrown during the trust chain building process.
+ */
+export class BuildTrustChainError extends FederationError {
+  code = "ERR_FED_BUILD_TRUST_CHAIN_FAILED";
+  constructor(message, details) {
+    super(message, details);
+  }
+}
+
+/**
+ * Error thrown when the Trust Anchor's key is missing a 'kid'.
+ */
+export class TrustAnchorKidMissingError extends FederationError {
+  code = "ERR_FED_TRUST_ANCHOR_KID_MISSING";
+  constructor() {
+    let message = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "Missing 'kid' in provided Trust Anchor key.";
+    super(message, undefined);
+  }
+}
+
+/**
+ * Error thrown if the Relying Party is not found in the Trust Anchor's federation list.
+ */
+export class RelyingPartyNotAuthorizedError extends FederationError {
+  code = "ERR_FED_RELYING_PARTY_NOT_AUTHORIZED";
+  constructor(message, details) {
+    super(message, details);
+  }
+}
+
+/**
+ * Error thrown when a 'federation_fetch_endpoint' is missing in an entity's configuration.
+ */
+export class MissingFederationFetchEndpointError extends FederationError {
+  code = "ERR_FED_MISSING_FEDERATION_FETCH_ENDPOINT";
+  constructor(message, details) {
+    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) {
+    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, details) {
+    super(message, details);
+  }
+}
+//# sourceMappingURL=errors.js.map

package/lib/module/trust/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["IoWalletError","serializeAttrs","FederationError","constructor","message","details","name","TrustChainEmptyError","code","arguments","length","undefined","TrustChainTokenMissingError","TrustChainRenewalError","FederationListParseError","BuildTrustChainError","TrustAnchorKidMissingError","RelyingPartyNotAuthorizedError","MissingFederationFetchEndpointError","MissingX509CertsError","X509ValidationError"],"sourceRoot":"../../../src","sources":["trust/errors.ts"],"mappings":"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"}