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

package/src/trust/api/index.ts

@@ -0,0 +1,57 @@
+import { type X509CertificateOptions } from "@pagopa/io-react-native-crypto";
+import type { TrustAnchorConfig } from "./TrustAnchorConfig";
+import type { ParsedToken } from "../common/utils";
+
+type FetchContext = { appFetch?: GlobalFetch["fetch"] };
+
+export interface TrustApi {
+  /**
+   * Get the common Trust Anchor Configuration, which is uniform across versions.
+   *
+   * @param trustAnchorBaseUrl The Trust Anchor base URL
+   * @returns The Trust Anchor Configuration object
+   */
+  getTrustAnchorEntityConfiguration(
+    trustAnchorBaseUrl: string,
+    ctx?: FetchContext
+  ): Promise<TrustAnchorConfig>;
+
+  /**
+   * Build a not-verified trust chain for a given Relying Party (RP) entity.
+   *
+   * @param relyingPartyEntityBaseUrl The base URL of the RP entity
+   * @param trustAnchorConfig The entity configuration of the known trust anchor.
+   * @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.
+   */
+  buildTrustChain(
+    relyingPartyEntityBaseUrl: string,
+    trustAnchorConfig: TrustAnchorConfig,
+    appFetch?: GlobalFetch["fetch"]
+  ): Promise<string[]>;
+
+  /**
+   * Verify a given trust chain is actually valid.
+   * It can handle fast chain renewal, which means we try to fetch a fresh version of each statement.
+   *
+   * @param trustAnchorEntity The entity configuration of the known trust anchor
+   * @param chain The chain of statements to be validated
+   * @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
+   */
+  verifyTrustChain(
+    trustAnchorEntity: TrustAnchorConfig,
+    chain: string[],
+    x509Options?: X509CertificateOptions,
+    ctx?: {
+      appFetch?: GlobalFetch["fetch"];
+      renewOnFail?: boolean;
+    }
+  ): Promise<ParsedToken[]>;
+}
+
+export { type TrustAnchorConfig };

package/src/trust/common/build-chain.ts

@@ -0,0 +1,161 @@
+import {
+  BuildTrustChainError,
+  MissingFederationFetchEndpointError,
+  RelyingPartyNotAuthorizedError,
+  TrustAnchorKidMissingError,
+} from "./errors";
+import {
+  decode,
+  getFederationList,
+  getSignedEntityConfiguration,
+  getSignedEntityStatement,
+  verify,
+} from "./utils";
+import { z } from "zod";
+import type { TrustApi } from "../api";
+import type { BaseEntityConfiguration, EntityStatement } from "./types";
+
+type BuilderConfig = {
+  EntityStatementShape: z.ZodType<EntityStatement>;
+  EntityConfigurationShape: z.ZodType<BaseEntityConfiguration>;
+};
+
+/**
+ * Factory function to create `buildTrustChain`.
+ * @param config Version specific Entity shapes
+ * @returns `buildTrustChain` function compliant with the public API
+ */
+export function createBuildTrustChain(
+  config: BuilderConfig
+): TrustApi["buildTrustChain"] {
+  return async function buildTrustChain(
+    relyingPartyEntityBaseUrl,
+    trustAnchorConfig,
+    appFetch = fetch
+  ) {
+    // 1: Verify if the RP is authorized by the Trust Anchor's federation list
+    // Extract the Trust Anchor's signing key and federation_list_endpoint
+    // (we assume the TA has only one key, as per spec)
+    const trustAnchorKey = trustAnchorConfig.keys[0];
+
+    if (!trustAnchorKey) {
+      throw new BuildTrustChainError(
+        "Cannot verify trust anchor: missing signing key in entity configuration."
+      );
+    }
+
+    const federationListEndpoint =
+      trustAnchorConfig.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 }
+        );
+      }
+    }
+
+    const gatherTrustChain = createGatherTrustChain(config);
+
+    // 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 chainTrustAnchorJwt = trustChain[trustChain.length - 1];
+    if (!chainTrustAnchorJwt) {
+      throw new BuildTrustChainError(
+        "Cannot verify trust anchor: missing entity configuration in gathered chain.",
+        { relyingPartyUrl: relyingPartyEntityBaseUrl }
+      );
+    }
+
+    if (!trustAnchorKey.kid) {
+      throw new TrustAnchorKidMissingError();
+    }
+
+    await verify(chainTrustAnchorJwt, trustAnchorKey.kid, [trustAnchorKey]);
+
+    return trustChain;
+  };
+}
+
+/**
+ * Factory function to create `gatherTrustChain`.
+ * @param config Version specific Entity shapes
+ * @returns `gatherTrustChain` function.
+ */
+export function createGatherTrustChain({
+  EntityConfigurationShape,
+  EntityStatementShape,
+}: BuilderConfig) {
+  return 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 = EntityConfigurationShape.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 = EntityConfigurationShape.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
+    EntityStatementShape.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/common/errors.ts

@@ -0,0 +1,138 @@
+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.
+ */
+export class FederationError extends IoWalletError {
+  public readonly details: Record<string, unknown> | undefined;
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(details ? serializeAttrs({ message, ...details }) : message);
+    this.name = this.constructor.name;
+    this.details = details;
+  }
+}
+
+/**
+ * Error thrown when a trust chain is unexpectedly empty.
+ */
+export class TrustChainEmptyError extends FederationError {
+  code = "ERR_FED_TRUST_CHAIN_EMPTY";
+  constructor(message = "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: string, details?: { index?: number }) {
+    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: string,
+    details?: { originalChain?: string[]; [key: string]: unknown }
+  ) {
+    super(message, details);
+  }
+}
+
+export class FederationListParseError extends FederationError {
+  code = "ERR_FED_FEDERATION_LIST_PARSE_FAILED";
+  constructor(message: string, details: { url: string; parseError?: string }) {
+    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: string,
+    details?: {
+      relyingPartyUrl?: string;
+      trustAnchorKid?: string;
+      [key: string]: unknown;
+    }
+  ) {
+    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(message = "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: string,
+    details: { relyingPartyUrl: string; federationListEndpoint?: string }
+  ) {
+    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: string,
+    details: { entityBaseUrl: string; missingInEntityUrl: string }
+  ) {
+    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/common/types.ts

@@ -0,0 +1,78 @@
+import * as z from "zod";
+import { JWK } from "../../utils/jwk";
+import { UnixTime } from "../../utils/zod";
+
+export const TrustMark = z.object({ id: z.string(), trust_mark: z.string() });
+export type TrustMark = z.infer<typeof TrustMark>;
+
+export type EntityStatement = z.infer<typeof EntityStatement>;
+export const EntityStatement = z.object({
+  header: z.object({
+    typ: z.literal("entity-statement+jwt"),
+    alg: z.string(),
+    kid: z.string(),
+  }),
+  payload: z.object({
+    iss: z.string(),
+    sub: z.string(),
+    jwks: z.object({ keys: z.array(JWK) }),
+    trust_marks: z.array(TrustMark).optional(),
+    iat: z.number(),
+    exp: z.number(),
+  }),
+});
+
+export type EntityConfigurationHeader = z.infer<
+  typeof EntityConfigurationHeader
+>;
+export const EntityConfigurationHeader = z.object({
+  typ: z.literal("entity-statement+jwt"),
+  alg: z.string(),
+  kid: z.string(),
+});
+
+/**
+ * @see https://openid.net/specs/openid-federation-1_0-46.html
+ */
+export const FederationEntityMetadata = z
+  .object({
+    federation_fetch_endpoint: z.string().optional(),
+    federation_list_endpoint: z.string().optional(),
+    federation_resolve_endpoint: z.string().optional(),
+    federation_trust_mark_status_endpoint: z.string().optional(),
+    federation_trust_mark_list_endpoint: z.string().optional(),
+    federation_trust_mark_endpoint: z.string().optional(),
+    federation_historical_keys_endpoint: z.string().optional(),
+    endpoint_auth_signing_alg_values_supported: z.string().optional(),
+    organization_name: z.string().optional(),
+    homepage_uri: z.string().optional(),
+    policy_uri: z.string().optional(),
+    logo_uri: z.string().optional(),
+    contacts: z.array(z.string()).optional(),
+  })
+  .passthrough();
+
+// Structure common to every Entity Configuration document
+export type BaseEntityConfiguration = z.infer<typeof BaseEntityConfiguration>;
+export const BaseEntityConfiguration = z.object({
+  header: EntityConfigurationHeader,
+  payload: z
+    .object({
+      iss: z.string(),
+      sub: z.string(),
+      iat: UnixTime,
+      exp: UnixTime,
+      authority_hints: z.array(z.string()).optional(),
+      metadata: z
+        .object({
+          federation_entity: FederationEntityMetadata,
+        })
+        .passthrough(),
+      jwks: z.object({
+        keys: z.array(JWK),
+      }),
+    })
+    .passthrough(),
+});
+
+export const FederationListResponse = z.array(z.string());

package/src/trust/common/utils.ts

@@ -0,0 +1,150 @@
+import {
+  decode as decodeJwt,
+  verify as verifyJwt,
+} from "@pagopa/io-react-native-jwt";
+
+import { hasStatusOrThrow } from "../../utils/misc";
+import type { JWK, JWTDecodeResult } from "../../utils/jwk";
+import { FederationError, FederationListParseError } from "./errors";
+import type { TrustAnchorConfig } from "../api/TrustAnchorConfig";
+import { FederationListResponse } from "./types";
+
+export type FetchOptions = {
+  appFetch?: GlobalFetch["fetch"];
+};
+
+export type ParsedToken = {
+  header: JWTDecodeResult["protectedHeader"];
+  payload: JWTDecodeResult["payload"];
+};
+
+// Verify a token signature
+// The kid is extracted from the token header
+export const verify = async (
+  token: string,
+  kid: string,
+  jwks: JWK[]
+): Promise<ParsedToken> => {
+  const jwk = jwks.find((k) => k.kid === kid);
+  if (!jwk) {
+    throw new Error(`Invalid kid: ${kid}, token: ${token}`);
+  }
+  const { protectedHeader: header, payload } = await verifyJwt(token, jwk);
+  return { header, payload };
+};
+
+/**
+ * Return type for this function is necessary to avoid an issue during the bob build process.
+ * It seems like typescript can't correctly infer the return type of the function.
+ */
+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: TrustAnchorConfig
+): string {
+  const taHeaderKid = trustAnchorEntity.jwt.header.kid;
+  const taSigningJwk = trustAnchorEntity.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" }
+  );
+}
+
+/**
+ * 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 }: FetchOptions = {}
+): 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 }: FetchOptions = {}
+) {
+  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 }: FetchOptions = {}
+): 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;
+    });
+}