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

package/src/sd-jwt/__test__/index.test.ts

@@ -3,39 +3,14 @@ import { decode, disclose } from "../index";
 
 import { encodeBase64, decodeBase64 } from "@pagopa/io-react-native-jwt";
 import { SdJwt4VC } from "../types";
+import { pid } from "../__mocks__/sd-jwt";
 
-// Examples from https://www.ietf.org/archive/id/draft-terbu-sd-jwt-vc-02.html#name-example-4
-// but adapted to adhere to format declared in https://italia.github.io/eudi-wallet-it-docs/versione-corrente/en/pid-eaa-data-model.html#id2
-// In short, the token is a Frankenstein composed as follows:
-//  - the header is taken from the italian specification, with kid and alg valued according to the signing keys
-//  - disclosures are taken from the SD-JWT-4-VC standard
-//  - payload is taken from the italian specification, but _sd are compiled with:
-//    - "address" is used as verification._sd
-//    - all others disclosures are in claims._sd
-const token =
-  "eyJraWQiOiItRl82VWdhOG4zVmVnalkyVTdZVUhLMXpMb2FELU5QVGM2M1JNSVNuTGF3IiwidHlwIjoidmMrc2Qtand0IiwiYWxnIjoiRVMyNTYifQ.eyJfc2QiOlsiMHExRDVKbWF2NnBRYUVoX0pfRmN2X3VOTk1RSWdDeWhRT3hxbFk0bDNxVSIsIktDSi1BVk52ODhkLXhqNnNVSUFPSnhGbmJVaDNySFhES2tJSDFsRnFiUnMiLCJNOWxvOVl4RE5JWHJBcTJxV2VpQ0E0MHpwSl96WWZGZFJfNEFFQUxjUnRVIiwiY3pnalVrMG5xUkNzd1NoQ2hDamRTNkExLXY0N2RfcVRDU0ZJdklIaE1vSSIsIm5HblFyN2NsbTN0ZlRwOHlqTF91SHJEU090elIyUFZiOFM3R2VMZEFxQlEiLCJ4TklWd2xwU3NhWjhDSlNmMGd6NXhfNzVWUldXYzZWMW1scGVqZENycVVzIl0sInN1YiI6IjIxNmY4OTQ2LTllY2ItNDgxOS05MzA5LWMwNzZmMzRhN2UxMSIsIl9zZF9hbGciOiJzaGEtMjU2IiwidmN0IjoiUGVyc29uSWRlbnRpZmljYXRpb25EYXRhIiwiaXNzIjoiaHR0cHM6Ly9wcmUuZWlkLndhbGxldC5pcHpzLml0IiwiY25mIjp7Imp3ayI6eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2Iiwia2lkIjoiUnYzVy1FaUtwdkJUeWs1eVp4dnJldi03TURCNlNselVDQm9fQ1FqamRkVSIsIngiOiIwV294N1F0eVBxQnlnMzVNSF9YeUNjbmQ1TGUtSm0wQVhIbFVnREJBMDNZIiwieSI6ImVFaFZ2ZzFKUHFOZDNEVFNhNG1HREdCbHdZNk5QLUVaYkxiTkZYU1h3SWcifX0sImV4cCI6MTc1MTU0NjU3Niwic3RhdHVzIjp7InN0YXR1c19hdHRlc3RhdGlvbiI6eyJjcmVkZW50aWFsX2hhc2hfYWxnIjoic2hhLTI1NiJ9fX0.qXHA2oqr8trX4fGxpxpUft2GX380TM3pzfo1MYAsDjUC8HsODA-4rdRWAvDe2zYP57x4tJU7eiABkd1Kmln9yQ~WyJrSkRFUDhFYU5URU1CRE9aelp6VDR3IiwidW5pcXVlX2lkIiwiVElOSVQtTFZMREFBODVUNTBHNzAyQiJd~WyJ6SUF5VUZ2UGZJcEUxekJxeEk1aGFRIiwiYmlydGhfZGF0ZSIsIjE5ODUtMTItMTAiXQ~WyJHcjNSM3MyOTBPa1FVbS1ORlR1OTZBIiwidGF4X2lkX2NvZGUiLCJUSU5JVC1MVkxEQUE4NVQ1MEc3MDJCIl0~WyJHeE9SYWxNQWVsZlowZWRGSmpqWVV3IiwiZ2l2ZW5fbmFtZSIsIkFkYSJd~WyJfdlY1UklrbDBJT0VYS290czlrdDF3IiwiZmFtaWx5X25hbWUiLCJMb3ZlbGFjZSJd~WyJDajV0Y2NSNzJKd3J6ZTJUVzRhLXdnIiwiaWF0IiwxNzIwMDEwNTc1XQ";
-
-const unsigned =
-  "eyJraWQiOiItRl82VWdhOG4zVmVnalkyVTdZVUhLMXpMb2FELU5QVGM2M1JNSVNuTGF3IiwidHlwIjoidmMrc2Qtand0IiwiYWxnIjoiRVMyNTYifQ.eyJfc2QiOlsiMHExRDVKbWF2NnBRYUVoX0pfRmN2X3VOTk1RSWdDeWhRT3hxbFk0bDNxVSIsIktDSi1BVk52ODhkLXhqNnNVSUFPSnhGbmJVaDNySFhES2tJSDFsRnFiUnMiLCJNOWxvOVl4RE5JWHJBcTJxV2VpQ0E0MHpwSl96WWZGZFJfNEFFQUxjUnRVIiwiY3pnalVrMG5xUkNzd1NoQ2hDamRTNkExLXY0N2RfcVRDU0ZJdklIaE1vSSIsIm5HblFyN2NsbTN0ZlRwOHlqTF91SHJEU090elIyUFZiOFM3R2VMZEFxQlEiLCJ4TklWd2xwU3NhWjhDSlNmMGd6NXhfNzVWUldXYzZWMW1scGVqZENycVVzIl0sInN1YiI6IjIxNmY4OTQ2LTllY2ItNDgxOS05MzA5LWMwNzZmMzRhN2UxMSIsIl9zZF9hbGciOiJzaGEtMjU2IiwidmN0IjoiUGVyc29uSWRlbnRpZmljYXRpb25EYXRhIiwiaXNzIjoiaHR0cHM6Ly9wcmUuZWlkLndhbGxldC5pcHpzLml0IiwiY25mIjp7Imp3ayI6eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2Iiwia2lkIjoiUnYzVy1FaUtwdkJUeWs1eVp4dnJldi03TURCNlNselVDQm9fQ1FqamRkVSIsIngiOiIwV294N1F0eVBxQnlnMzVNSF9YeUNjbmQ1TGUtSm0wQVhIbFVnREJBMDNZIiwieSI6ImVFaFZ2ZzFKUHFOZDNEVFNhNG1HREdCbHdZNk5QLUVaYkxiTkZYU1h3SWcifX0sImV4cCI6MTc1MTU0NjU3Niwic3RhdHVzIjp7InN0YXR1c19hdHRlc3RhdGlvbiI6eyJjcmVkZW50aWFsX2hhc2hfYWxnIjoic2hhLTI1NiJ9fX0";
-
-const signature =
-  "qXHA2oqr8trX4fGxpxpUft2GX380TM3pzfo1MYAsDjUC8HsODA-4rdRWAvDe2zYP57x4tJU7eiABkd1Kmln9yQ";
-
-const signed = `${unsigned}.${signature}`;
-
-const tokenizedDisclosures = [
-  "WyJrSkRFUDhFYU5URU1CRE9aelp6VDR3IiwidW5pcXVlX2lkIiwiVElOSVQtTFZMREFBODVUNTBHNzAyQiJd",
-  "WyJ6SUF5VUZ2UGZJcEUxekJxeEk1aGFRIiwiYmlydGhfZGF0ZSIsIjE5ODUtMTItMTAiXQ",
-  "WyJHcjNSM3MyOTBPa1FVbS1ORlR1OTZBIiwidGF4X2lkX2NvZGUiLCJUSU5JVC1MVkxEQUE4NVQ1MEc3MDJCIl0",
-  "WyJHeE9SYWxNQWVsZlowZWRGSmpqWVV3IiwiZ2l2ZW5fbmFtZSIsIkFkYSJd",
-  "WyJfdlY1UklrbDBJT0VYS290czlrdDF3IiwiZmFtaWx5X25hbWUiLCJMb3ZlbGFjZSJd",
-  "WyJDajV0Y2NSNzJKd3J6ZTJUVzRhLXdnIiwiaWF0IiwxNzIwMDEwNTc1XQ",
-];
+const { token, signed, tokenizedDisclosures } = pid;
 
 const sdJwt = {
   header: {
     kid: "-F_6Uga8n3VegjY2U7YUHK1zLoaD-NPTc63RMISnLaw",
-    typ: "vc+sd-jwt",
+    typ: "dc+sd-jwt",
     alg: "ES256",
   },
   payload: {
@@ -50,7 +25,11 @@ const sdJwt = {
     sub: "216f8946-9ecb-4819-9309-c076f34a7e11",
     _sd_alg: "sha-256",
     vct: "PersonIdentificationData",
+    "vct#integrity":
+      "13e25888ac7b8a3a6d61440da787fccc81654e61085732bcacd89b36aec32675",
     iss: "https://pre.eid.wallet.ipzs.it",
+    issuing_country: "IT",
+    issuing_authority: "Istituto Poligrafico e Zecca dello Stato",
     cnf: {
       jwk: {
         kty: "EC",
@@ -62,7 +41,7 @@ const sdJwt = {
     },
     exp: 1751546576,
     status: {
-      status_attestation: {
+      status_assertion: {
         credential_hash_alg: "sha-256",
       },
     },

package/src/sd-jwt/__test__/types.test.ts

@@ -5,7 +5,7 @@ describe("SdJwt4VC", () => {
     // example provided at https://italia.github.io/eidas-it-wallet-docs/en/pid-data-model.html
     const token = {
       header: {
-        typ: "vc+sd-jwt",
+        typ: "dc+sd-jwt",
         alg: "RS512",
         kid: "dB67gL7ck3TFiIAf7N6_7SHvqk0MDYMEQcoGGlkUAAw",
       },
@@ -21,7 +21,11 @@ describe("SdJwt4VC", () => {
         sub: "216f8946-9ecb-4819-9309-c076f34a7e11",
         _sd_alg: "sha-256",
         vct: "PersonIdentificationData",
+        "vct#integrity":
+          "13e25888ac7b8a3a6d61440da787fccc81654e61085732bcacd89b36aec32675",
         iss: "https://pidprovider.example.com",
+        issuing_country: "IT",
+        issuing_authority: "Istituto Poligrafico e Zecca dello Stato",
         cnf: {
           jwk: {
             kty: "EC",
@@ -33,7 +37,7 @@ describe("SdJwt4VC", () => {
         },
         exp: 1751107255,
         status: {
-          status_attestation: {
+          status_assertion: {
             credential_hash_alg: "sha-256",
           },
         },

package/src/sd-jwt/__test__/utils.test.ts

@@ -0,0 +1,37 @@
+import { getVerification } from "..";
+import { pid } from "../__mocks__/sd-jwt";
+
+const { signed, token } = pid;
+
+describe("SD-JWT getVerification", () => {
+  it("extracts the verification claims correctly", () => {
+    const disclosure =
+      "WyJxTGxVdkNKY3hwX3d4MVY5dHFPbFFRIiwidmVyaWZpY2F0aW9uIix7ImV2aWRlbmNlIjpbeyJhdHRlc3RhdGlvbiI6eyJkYXRlX29mX2lzc3VhbmNlIjoiMjAyNS0wNi0yMyIsInZvdWNoZXIiOnsib3JnYW5pemF0aW9uIjoiTWluaXN0ZXJvIGRlbGwnSW50ZXJubyJ9LCJ0eXBlIjoiZGlnaXRhbF9hdHRlc3RhdGlvbiIsInJlZmVyZW5jZV9udW1iZXIiOiIxMjM0NTY3ODkifSwidGltZSI6IjIwMjUtMDYtMjNUMTM6MTQ6MjVaIiwidHlwZSI6InZvdWNoIn1dLCJ0cnVzdF9mcmFtZXdvcmsiOiJpdF9jaWUiLCJhc3N1cmFuY2VfbGV2ZWwiOiJoaWdoIn1d";
+    expect(getVerification(`${signed}~${disclosure}`)).toEqual({
+      evidence: [
+        {
+          attestation: {
+            date_of_issuance: "2025-06-23",
+            voucher: { organization: "Ministero dell'Interno" },
+            type: "digital_attestation",
+            reference_number: "123456789",
+          },
+          time: "2025-06-23T13:14:25Z",
+          type: "vouch",
+        },
+      ],
+      trust_framework: "it_cie",
+      assurance_level: "high",
+    });
+  });
+
+  it("returns undefined when the verification claim is not found", () => {
+    expect(getVerification(token)).toBeUndefined();
+  });
+
+  it("throws when the verification claim is invalid", () => {
+    const disclosure =
+      "WyJxTGxVdkNKY3hwX3d4MVY5dHFPbFFRIiwidmVyaWZpY2F0aW9uIix7InRydXN0X2ZyYW1ld29yayI6ICJpdF9jaWUiLCJhc3N1cmFuY2VfbGV2ZWwiOiAic3Vic3RhbnRpYWwifV0";
+    expect(() => getVerification(`${signed}~${disclosure}`)).toThrow();
+  });
+});

package/src/sd-jwt/index.ts

@@ -10,6 +10,8 @@ import * as Errors from "./errors";
 import { Base64 } from "js-base64";
 import { type Presentation } from "../credential/presentation/types";
 
+export * from "./utils";
+
 const decodeDisclosure = (encoded: string): DisclosureWithEncoded => {
   const utf8String = Base64.decode(encoded); // Decode Base64 into UTF-8 string
   const decoded = Disclosure.parse(JSON.parse(utf8String));

package/src/sd-jwt/types.ts

@@ -36,7 +36,7 @@ export type DisclosureWithEncoded = {
 export type SdJwt4VC = z.infer<typeof SdJwt4VC>;
 export const SdJwt4VC = z.object({
   header: z.object({
-    typ: z.literal("vc+sd-jwt"),
+    typ: z.literal("dc+sd-jwt"),
     alg: z.string(),
     kid: z.string().optional(),
   }),
@@ -48,7 +48,7 @@ export const SdJwt4VC = z.object({
       exp: UnixTime,
       _sd_alg: z.literal("sha-256"),
       status: z.object({
-        status_attestation: z.object({
+        status_assertion: z.object({
           credential_hash_alg: z.literal("sha-256"),
         }),
       }),
@@ -56,7 +56,54 @@ export const SdJwt4VC = z.object({
         jwk: JWK,
       }),
       vct: z.string(),
+      "vct#integrity": z.string(),
+      issuing_authority: z.string(),
+      issuing_country: z.string(),
     }),
     ObfuscatedDisclosures
   ),
 });
+
+/**
+ * Object containing User authentication and User data verification information.
+ * Useful to extract the assurance level to determine L2/L3 authentication.
+ */
+export type Verification = z.infer<typeof Verification>;
+export const Verification = z.object({
+  trust_framework: z.string(),
+  assurance_level: z.string(),
+  evidence: z.array(
+    z.object({
+      type: z.literal("vouch"),
+      time: z.string(),
+      attestation: z.object({
+        type: z.literal("digital_attestation"),
+        reference_number: z.string(),
+        date_of_issuance: z.string(),
+        voucher: z.object({ organization: z.string() }),
+      }),
+    })
+  ),
+});
+
+/**
+ * Metadata for a digital credential. This information is retrieved from the URL defined in the `vct` claim.
+ *
+ * @see https://italia.github.io/eid-wallet-it-docs/v0.9.1/en/pid-eaa-data-model.html#digital-credential-metadata-type
+ */
+export type TypeMetadata = z.infer<typeof TypeMetadata>;
+export const TypeMetadata = z.object({
+  name: z.string(),
+  description: z.string(),
+  data_source: z.object({
+    trust_framework: z.string(),
+    authentic_source: z.object({
+      organization_name: z.string(),
+      organization_code: z.string(),
+      contacts: z.array(z.string()),
+      homepage_uri: z.string().url(),
+      logo_uri: z.string().url(),
+    }),
+  }),
+  // TODO: add more fields
+});

package/src/sd-jwt/utils.ts

@@ -0,0 +1,73 @@
+import { sha256ToBase64 } from "@pagopa/io-react-native-jwt";
+import { hasStatusOrThrow } from "../utils/misc";
+import { TypeMetadata, Verification } from "./types";
+import {
+  IoWalletError,
+  IssuerResponseError,
+  ValidationFailed,
+} from "../utils/errors";
+import { decode } from ".";
+import { getValueFromDisclosures } from "./converters";
+
+/**
+ * Retrieve the Type Metadata for a credential and verify its integrity.
+ * @param vct The VCT as a valid HTTPS url
+ * @param vctIntegrity The integrity hash
+ * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
+ * @returns The credential metadata {@link TypeMetadata}
+ */
+export const fetchTypeMetadata = async (
+  vct: string,
+  vctIntegrity: string,
+  context: {
+    appFetch?: GlobalFetch["fetch"];
+  } = {}
+): Promise<TypeMetadata> => {
+  const { appFetch = fetch } = context;
+  const { origin, pathname } = new URL(vct);
+
+  const metadata = await appFetch(`${origin}/.well-known/vct${pathname}`, {
+    headers: {
+      "Content-Type": "application/json",
+    },
+  })
+    .then(hasStatusOrThrow(200, IssuerResponseError))
+    .then((res) => res.json())
+    .then(TypeMetadata.parse);
+
+  const [alg, hash] = vctIntegrity.split(/-(.*)/s);
+
+  if (alg !== "sha256") {
+    throw new IoWalletError(`${alg} algorithm is not supported`);
+  }
+
+  // TODO: [SIW-2264] check if the hash is correctly calculated
+  const metadataHash = await sha256ToBase64(JSON.stringify(metadata));
+
+  if (metadataHash !== hash) {
+    throw new ValidationFailed({
+      message: "Unable to verify VCT integrity",
+      reason: "vct#integrity does not match the metadata hash",
+    });
+  }
+
+  return metadata;
+};
+
+/**
+ * Extract and validate the `verification` claim from disclosures.
+ * @param credentialSdJwt The raw credential SD-JWT
+ * @returns The verification claim or undefined if it wasn't found
+ */
+export const getVerification = (
+  credentialSdJwt: string
+): Verification | undefined => {
+  const { disclosures } = decode(credentialSdJwt);
+  const verificationDisclosure = getValueFromDisclosures(
+    disclosures.map((d) => d.decoded),
+    "verification"
+  );
+  return verificationDisclosure
+    ? Verification.parse(verificationDisclosure)
+    : undefined;
+};

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