@pagopa/io-react-native-wallet 2.0.0-next.0 → 2.0.0-next.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/build-chain.ts

@@ -0,0 +1,395 @@
+import type { JWK } from "../utils/jwk";
+import {
+  BuildTrustChainError,
+  FederationListParseError,
+  MissingFederationFetchEndpointError,
+  RelyingPartyNotAuthorizedError,
+  TrustAnchorKidMissingError,
+} from "./errors";
+import { decode, verify } from "./utils";
+import {
+  CredentialIssuerEntityConfiguration,
+  EntityConfiguration,
+  EntityStatement,
+  FederationListResponse,
+  RelyingPartyEntityConfiguration,
+  TrustAnchorEntityConfiguration,
+  WalletProviderEntityConfiguration,
+} from "./types";
+import { hasStatusOrThrow } from "../utils/misc";
+import { decode as decodeJwt } from "@pagopa/io-react-native-jwt";
+
+/**
+ * Fetch and parse the entity configuration document for a given federation entity.
+ * This is an inner method to serve public interfaces.
+ *
+ * To add another entity configuration type (example: Foo entity type):
+ *  - create its zod schema and type by inherit from the base type (example: FooEntityConfiguration = BaseEntityConfiguration.and(...))
+ *  - add such type to EntityConfiguration union
+ *  - add an overload to this function
+ *  - create a public function which use such type (example: getFooEntityConfiguration = (url, options) => Promise<FooEntityConfiguration>)
+ *
+ * @param entityBaseUrl The base url of the entity.
+ * @param schema The expected schema of the entity configuration, according to the kind of entity we are fetching from.
+ * @param options An optional object with additional options.
+ * @param options.appFetch An optional instance of the http client to be used.
+ * @returns The parsed entity configuration object
+ * @throws {IoWalletError} If the http request fails
+ * @throws Parse error if the document is not in the expected shape.
+ */
+async function fetchAndParseEntityConfiguration(
+  entityBaseUrl: string,
+  schema: typeof WalletProviderEntityConfiguration,
+  options?: {
+    appFetch?: GlobalFetch["fetch"];
+  }
+): Promise<WalletProviderEntityConfiguration>;
+async function fetchAndParseEntityConfiguration(
+  entityBaseUrl: string,
+  schema: typeof RelyingPartyEntityConfiguration,
+  options?: {
+    appFetch?: GlobalFetch["fetch"];
+  }
+): Promise<RelyingPartyEntityConfiguration>;
+async function fetchAndParseEntityConfiguration(
+  entityBaseUrl: string,
+  schema: typeof TrustAnchorEntityConfiguration,
+  options?: {
+    appFetch?: GlobalFetch["fetch"];
+  }
+): Promise<TrustAnchorEntityConfiguration>;
+async function fetchAndParseEntityConfiguration(
+  entityBaseUrl: string,
+  schema: typeof CredentialIssuerEntityConfiguration,
+  options?: {
+    appFetch?: GlobalFetch["fetch"];
+  }
+): Promise<CredentialIssuerEntityConfiguration>;
+async function fetchAndParseEntityConfiguration(
+  entityBaseUrl: string,
+  schema: typeof EntityConfiguration,
+  options?: {
+    appFetch?: GlobalFetch["fetch"];
+  }
+): Promise<EntityConfiguration>;
+async function fetchAndParseEntityConfiguration(
+  entityBaseUrl: string,
+  schema: /* FIXME: why is it different from "typeof EntityConfiguration"? */
+  | typeof CredentialIssuerEntityConfiguration
+    | typeof WalletProviderEntityConfiguration
+    | typeof RelyingPartyEntityConfiguration
+    | typeof TrustAnchorEntityConfiguration
+    | typeof EntityConfiguration,
+  {
+    appFetch = fetch,
+  }: {
+    appFetch?: GlobalFetch["fetch"];
+  } = {}
+) {
+  const responseText = await getSignedEntityConfiguration(entityBaseUrl, {
+    appFetch,
+  });
+
+  const responseJwt = decodeJwt(responseText);
+  return schema.parse({
+    header: responseJwt.protectedHeader,
+    payload: responseJwt.payload,
+  });
+}
+
+export const getWalletProviderEntityConfiguration = (
+  entityBaseUrl: Parameters<typeof fetchAndParseEntityConfiguration>[0],
+  options?: Parameters<typeof fetchAndParseEntityConfiguration>[2]
+) =>
+  fetchAndParseEntityConfiguration(
+    entityBaseUrl,
+    WalletProviderEntityConfiguration,
+    options
+  );
+
+export const getCredentialIssuerEntityConfiguration = (
+  entityBaseUrl: Parameters<typeof fetchAndParseEntityConfiguration>[0],
+  options?: Parameters<typeof fetchAndParseEntityConfiguration>[2]
+) =>
+  fetchAndParseEntityConfiguration(
+    entityBaseUrl,
+    CredentialIssuerEntityConfiguration,
+    options
+  );
+
+export const getTrustAnchorEntityConfiguration = (
+  entityBaseUrl: Parameters<typeof fetchAndParseEntityConfiguration>[0],
+  options?: Parameters<typeof fetchAndParseEntityConfiguration>[2]
+) =>
+  fetchAndParseEntityConfiguration(
+    entityBaseUrl,
+    TrustAnchorEntityConfiguration,
+    options
+  );
+
+export const getRelyingPartyEntityConfiguration = (
+  entityBaseUrl: Parameters<typeof fetchAndParseEntityConfiguration>[0],
+  options?: Parameters<typeof fetchAndParseEntityConfiguration>[2]
+) =>
+  fetchAndParseEntityConfiguration(
+    entityBaseUrl,
+    RelyingPartyEntityConfiguration,
+    options
+  );
+
+export const getEntityConfiguration = (
+  entityBaseUrl: Parameters<typeof fetchAndParseEntityConfiguration>[0],
+  options?: Parameters<typeof fetchAndParseEntityConfiguration>[2]
+) =>
+  fetchAndParseEntityConfiguration(entityBaseUrl, EntityConfiguration, options);
+
+/**
+ * Fetch and parse the entity statement document for a given federation entity.
+ *
+ * @param accreditationBodyBaseUrl The base url of the accreditation body which holds and signs the required entity statement
+ * @param subordinatedEntityBaseUrl The url that identifies the subordinate entity
+ * @param appFetch An optional instance of the http client to be used.
+ * @returns The parsed entity configuration object
+ * @throws {IoWalletError} If the http request fails
+ */
+export async function getEntityStatement(
+  accreditationBodyBaseUrl: string,
+  subordinatedEntityBaseUrl: string,
+  {
+    appFetch = fetch,
+  }: {
+    appFetch?: GlobalFetch["fetch"];
+  } = {}
+) {
+  const responseText = await getSignedEntityStatement(
+    accreditationBodyBaseUrl,
+    subordinatedEntityBaseUrl,
+    {
+      appFetch,
+    }
+  );
+
+  const responseJwt = decodeJwt(responseText);
+  return EntityStatement.parse({
+    header: responseJwt.protectedHeader,
+    payload: responseJwt.payload,
+  });
+}
+
+/**
+ * Fetch the signed entity configuration token for an entity
+ *
+ * @param entityBaseUrl The url of the entity to fetch
+ * @param appFetch (optional) fetch api implementation
+ * @returns The signed Entity Configuration token
+ */
+export async function getSignedEntityConfiguration(
+  entityBaseUrl: string,
+  {
+    appFetch = fetch,
+  }: {
+    appFetch?: GlobalFetch["fetch"];
+  } = {}
+): Promise<string> {
+  const wellKnownUrl = `${entityBaseUrl}/.well-known/openid-federation`;
+
+  return await appFetch(wellKnownUrl, {
+    method: "GET",
+  })
+    .then(hasStatusOrThrow(200))
+    .then((res) => res.text());
+}
+
+/**
+ * Fetch the entity statement document for a given federation entity.
+ *
+ * @param federationFetchEndpoint The exact endpoint provided by the parent EC's metadata.
+ * @param subordinatedEntityBaseUrl The url that identifies the subordinate entity.
+ * @param appFetch An optional instance of the http client to be used.
+ * @returns The signed entity statement token.
+ * @throws {IoWalletError} If the http request fails.
+ */
+export async function getSignedEntityStatement(
+  federationFetchEndpoint: string,
+  subordinatedEntityBaseUrl: string,
+  {
+    appFetch = fetch,
+  }: {
+    appFetch?: GlobalFetch["fetch"];
+  } = {}
+) {
+  const url = new URL(federationFetchEndpoint);
+  url.searchParams.set("sub", subordinatedEntityBaseUrl);
+
+  return await appFetch(url.toString(), {
+    method: "GET",
+  })
+    .then(hasStatusOrThrow(200))
+    .then((res) => res.text());
+}
+
+/**
+ * Fetch the federation list document from a given endpoint.
+ *
+ * @param federationListEndpoint The URL of the federation list endpoint.
+ * @param appFetch An optional instance of the http client to be used.
+ * @returns The federation list as an array of strings.
+ * @throws {IoWalletError} If the HTTP request fails.
+ * @throws {FederationError} If the result is not in the expected format.
+ */
+export async function getFederationList(
+  federationListEndpoint: string,
+  {
+    appFetch = fetch,
+  }: {
+    appFetch?: GlobalFetch["fetch"];
+  } = {}
+): Promise<string[]> {
+  return await appFetch(federationListEndpoint, {
+    method: "GET",
+  })
+    .then(hasStatusOrThrow(200))
+    .then((res) => res.json())
+    .then((json) => {
+      const result = FederationListResponse.safeParse(json);
+      if (!result.success) {
+        throw new FederationListParseError(
+          `Invalid federation list format received from ${federationListEndpoint}. Error: ${result.error.message}`,
+          { url: federationListEndpoint, parseError: result.error.toString() }
+        );
+      }
+      return result.data;
+    });
+}
+
+/**
+ * Build a not-verified trust chain for a given Relying Party (RP) entity.
+ *
+ * @param relyingPartyEntityBaseUrl The base URL of the RP entity
+ * @param trustAnchorKey The public key of the Trust Anchor (TA) entity
+ * @param appFetch An optional instance of the http client to be used.
+ * @returns A list of signed tokens that represent the trust chain, in the order of the chain (from the RP to the Trust Anchor)
+ * @throws {FederationError} When an element of the chain fails to parse or other build steps fail.
+ */
+export async function buildTrustChain(
+  relyingPartyEntityBaseUrl: string,
+  trustAnchorKey: JWK,
+  appFetch: GlobalFetch["fetch"] = fetch
+): Promise<string[]> {
+  // 1: Recursively gather the trust chain from the RP up to the Trust Anchor
+  const trustChain = await gatherTrustChain(
+    relyingPartyEntityBaseUrl,
+    appFetch
+  );
+
+  // 2: Trust Anchor signature verification
+  const trustAnchorJwt = trustChain[trustChain.length - 1];
+  if (!trustAnchorJwt) {
+    throw new BuildTrustChainError(
+      "Cannot verify trust anchor: missing entity configuration in gathered chain.",
+      { relyingPartyUrl: relyingPartyEntityBaseUrl }
+    );
+  }
+
+  if (!trustAnchorKey.kid) {
+    throw new TrustAnchorKidMissingError();
+  }
+
+  await verify(trustAnchorJwt, trustAnchorKey.kid, [trustAnchorKey]);
+
+  // 3: Check the federation list
+  const trustAnchorConfig = EntityConfiguration.parse(decode(trustAnchorJwt));
+  const federationListEndpoint =
+    trustAnchorConfig.payload.metadata.federation_entity
+      .federation_list_endpoint;
+
+  if (federationListEndpoint) {
+    const federationList = await getFederationList(federationListEndpoint, {
+      appFetch,
+    });
+
+    if (!federationList.includes(relyingPartyEntityBaseUrl)) {
+      throw new RelyingPartyNotAuthorizedError(
+        "Relying Party entity base URL is not authorized by the Trust Anchor's federation list.",
+        { relyingPartyUrl: relyingPartyEntityBaseUrl, federationListEndpoint }
+      );
+    }
+  }
+
+  return trustChain;
+}
+
+/**
+ * Recursively gather the trust chain for an entity and all its superiors.
+ * @param entityBaseUrl The base URL of the entity for which to gather the chain.
+ * @param appFetch An optional instance of the http client to be used.
+ * @param isLeaf Whether the current entity is the leaf of the chain.
+ * @returns A full ordered list of JWTs (ECs and ESs) forming the trust chain.
+ * @throws {FederationError} If any of the fetched documents fail to parse or other errors occur during the gathering process.
+ */
+async function gatherTrustChain(
+  entityBaseUrl: string,
+  appFetch: GlobalFetch["fetch"],
+  isLeaf: boolean = true
+): Promise<string[]> {
+  const chain: string[] = [];
+
+  // Fetch self-signed EC (only needed for the leaf)
+  const entityECJwt = await getSignedEntityConfiguration(entityBaseUrl, {
+    appFetch,
+  });
+  const entityEC = EntityConfiguration.parse(decode(entityECJwt));
+
+  if (isLeaf) {
+    // Only push EC for the leaf
+    chain.push(entityECJwt);
+  }
+
+  // Find authority_hints (parent, if any)
+  const authorityHints = entityEC.payload.authority_hints ?? [];
+  if (authorityHints.length === 0) {
+    // This is the Trust Anchor (no parent)
+    if (!isLeaf) {
+      chain.push(entityECJwt);
+    }
+    return chain;
+  }
+
+  const parentEntityBaseUrl = authorityHints[0]!;
+
+  // Fetch parent EC
+  const parentECJwt = await getSignedEntityConfiguration(parentEntityBaseUrl, {
+    appFetch,
+  });
+  const parentEC = EntityConfiguration.parse(decode(parentECJwt));
+
+  // Fetch ES
+  const federationFetchEndpoint =
+    parentEC.payload.metadata.federation_entity.federation_fetch_endpoint;
+  if (!federationFetchEndpoint) {
+    throw new MissingFederationFetchEndpointError(
+      `Missing federation_fetch_endpoint in parent's (${parentEntityBaseUrl}) configuration when gathering chain for ${entityBaseUrl}.`,
+      { entityBaseUrl, missingInEntityUrl: parentEntityBaseUrl }
+    );
+  }
+
+  const entityStatementJwt = await getSignedEntityStatement(
+    federationFetchEndpoint,
+    entityBaseUrl,
+    { appFetch }
+  );
+  // Validate the ES
+  EntityStatement.parse(decode(entityStatementJwt));
+
+  // Push this ES into the chain
+  chain.push(entityStatementJwt);
+
+  // Recurse into the parent
+  const parentChain = await gatherTrustChain(
+    parentEntityBaseUrl,
+    appFetch,
+    false
+  );
+
+  return chain.concat(parentChain);
+}

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);
+  }
+}