@pagopa/io-react-native-wallet 0.27.1 → 0.28.0

package/src/trust/index.ts

@@ -1,14 +1,18 @@
+import { decode, verify } from "./utils";
 import { decode as decodeJwt } from "@pagopa/io-react-native-jwt";
 import {
-  WalletProviderEntityConfiguration,
-  TrustAnchorEntityConfiguration,
   CredentialIssuerEntityConfiguration,
-  RelyingPartyEntityConfiguration,
   EntityConfiguration,
   EntityStatement,
+  FederationListResponse,
+  RelyingPartyEntityConfiguration,
+  TrustAnchorEntityConfiguration,
+  WalletProviderEntityConfiguration,
 } from "./types";
-import { validateTrustChain, renewTrustChain } from "./chain";
+import { renewTrustChain, validateTrustChain } from "./chain";
 import { hasStatusOrThrow } from "../utils/misc";
+import { IoWalletError } from "../utils/errors";
+import type { JWK } from "../utils/jwk";
 
 export type {
   WalletProviderEntityConfiguration,
@@ -24,9 +28,9 @@ export type {
  * 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 validate
- * @param options.renewOnFail Whether to renew the provided chain if the validation fails at first. Default: true
- * @param options.appFetch Fetch api implementation. Default: the built-in implementation
+ * @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
  * @returns The result of the chain validation
  * @throws {IoWalletError} When either validation or renewal fail
  */
@@ -54,7 +58,7 @@ export async function verifyTrustChain(
  * Fetch the signed entity configuration token for an entity
  *
  * @param entityBaseUrl The url of the entity to fetch
- * @param param.appFetch (optional) fetch api implemention
+ * @param appFetch (optional) fetch api implementation
  * @returns The signed Entity Configuration token
  */
 export async function getSignedEntityConfiguration(
@@ -86,6 +90,7 @@ export async function getSignedEntityConfiguration(
  *
  * @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
@@ -200,9 +205,9 @@ export const getEntityConfiguration = (
 /**
  * Fetch and parse the entity statement document for a given federation entity.
  *
- * @param accreditationBodyBaseUrl The base url of the accreditaion body which holds and signs the required entity statement
+ * @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 options.appFetch An optional instance of the http client to be used.
+ * @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
  * @throws Parse error if the document is not in the expected shape.
@@ -234,14 +239,14 @@ export async function getEntityStatement(
 /**
  * Fetch the entity statement document for a given federation entity.
  *
- * @param accreditationBodyBaseUrl The base url of the accreditaion body which holds and signs the required entity statement
- * @param subordinatedEntityBaseUrl The url that identifies the subordinate entity
- * @param options.appFetch An optional instance of the http client to be used.
- * @returns The signed entity statement token
- * @throws {IoWalletError} If the http request fails
+ * @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(
-  accreditationBodyBaseUrl: string,
+  federationFetchEndpoint: string,
   subordinatedEntityBaseUrl: string,
   {
     appFetch = fetch,
@@ -249,13 +254,173 @@ export async function getSignedEntityStatement(
     appFetch?: GlobalFetch["fetch"];
   } = {}
 ) {
-  const url = `${accreditationBodyBaseUrl}/fetch?${new URLSearchParams({
-    sub: subordinatedEntityBaseUrl,
-  })}`;
+  const url = new URL(federationFetchEndpoint);
+  url.searchParams.set("sub", subordinatedEntityBaseUrl);
 
-  return await appFetch(url, {
+  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 or the response cannot be parsed.
+ */
+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 IoWalletError(
+          `Invalid federation list format received from Trust Anchor: ${result.error.message}`
+        );
+      }
+      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 {IoWalletError} When an element of the chain fails to parse
+ * The result of this function can be used to validate the trust chain with {@link verifyTrustChain}
+ */
+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 IoWalletError(
+      "Cannot verify trust anchor: missing entity configuration."
+    );
+  }
+
+  if (!trustAnchorKey.kid) {
+    throw new IoWalletError("Missing 'kid' in provided Trust Anchor key.");
+  }
+
+  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 IoWalletError(
+        "Relying Party entity base URL is not authorized by the Trust Anchor's federation list."
+      );
+    }
+  }
+
+  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.
+ */
+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 IoWalletError(
+      "Missing federation_fetch_endpoint in parent's configuration."
+    );
+  }
+
+  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/types.ts

@@ -12,7 +12,6 @@ const RelyingPartyMetadata = z.object({
   jwks: z.object({ keys: z.array(JWK) }),
   contacts: z.array(z.string()).optional(),
 });
-//.passthrough();
 
 // Display metadata for a credential, used by the issuer to
 // instruct the Wallet Solution on how to render the credential correctly
@@ -50,7 +49,7 @@ const IssuanceErrorSupported = z.object({
   ),
 });
 
-// Metadata for a credentia which is supported by a Issuer
+// Metadata for a credential which is supported by an Issuer
 type SupportedCredentialMetadata = z.infer<typeof SupportedCredentialMetadata>;
 const SupportedCredentialMetadata = z.object({
   format: z.union([z.literal("vc+sd-jwt"), z.literal("vc+mdoc-cbor")]),
@@ -74,7 +73,7 @@ export const EntityStatement = z.object({
     iss: z.string(),
     sub: z.string(),
     jwks: z.object({ keys: z.array(JWK) }),
-    trust_marks: z.array(TrustMark),
+    trust_marks: z.array(TrustMark).optional(),
     iat: z.number(),
     exp: z.number(),
   }),
@@ -90,7 +89,7 @@ export const EntityConfigurationHeader = z.object({
 });
 
 /**
- * @see https://openid.net/specs/openid-connect-federation-1_0-29.html#name-federation-entity
+ * @see https://openid.net/specs/openid-federation-1_0-41.html
  */
 const FederationEntityMetadata = z
   .object({
@@ -99,6 +98,9 @@ const FederationEntityMetadata = z
     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(),
@@ -107,7 +109,7 @@ const FederationEntityMetadata = z
   })
   .passthrough();
 
-// Structuire common to every Entity Configuration document
+// Structure common to every Entity Configuration document
 const BaseEntityConfiguration = z.object({
   header: EntityConfigurationHeader,
   payload: z
@@ -232,3 +234,5 @@ export const EntityConfiguration = z.union(
     description: "Any kind of Entity Configuration allowed in the ecosystem",
   }
 );
+
+export const FederationListResponse = z.array(z.string());

package/src/trust/utils.ts

@@ -0,0 +1,32 @@
+import {
+  decode as decodeJwt,
+  verify as verifyJwt,
+} from "@pagopa/io-react-native-jwt";
+
+import type { JWK } from "../utils/jwk";
+import type { JWTDecodeResult } from "@pagopa/io-react-native-jwt/lib/typescript/types";
+
+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 };
+};
+
+export const decode = (token: string) => {
+  const { protectedHeader: header, payload } = decodeJwt(token);
+  return { header, payload };
+};

package/src/utils/errors.ts

@@ -225,8 +225,8 @@ export const isWalletProviderResponseError = (
 type ErrorCodeMap<T> = T extends typeof IssuerResponseError
   ? IssuerResponseErrorCode
   : T extends typeof WalletProviderResponseError
-    ? WalletProviderResponseErrorCode
-    : never;
+  ? WalletProviderResponseErrorCode
+  : never;
 
 type ErrorCase<T> = {
   code: ErrorCodeMap<T>;

package/src/utils/misc.ts

@@ -37,8 +37,8 @@ export const parseRawHttpResponse = <T extends Record<string, unknown>>(
 export type Out<FN> = FN extends (...args: any[]) => Promise<any>
   ? Awaited<ReturnType<FN>>
   : FN extends (...args: any[]) => any
-    ? ReturnType<FN>
-    : never;
+  ? ReturnType<FN>
+  : never;
 
 /**
  * TODO [SIW-1310]: replace this function with a cryptographically secure one.

package/src/wallet-instance/index.ts

@@ -87,3 +87,16 @@ export async function getWalletInstanceStatus(context: {
     path: { id: context.id },
   });
 }
+
+/**
+ * Get the status of the current Wallet Instance.
+ * @returns Details on the status of the current Wallet Instance
+ */
+export async function getCurrentWalletInstanceStatus(context: {
+  walletProviderBaseUrl: string;
+  appFetch?: GlobalFetch["fetch"];
+}): Promise<WalletInstanceData> {
+  const api = getWalletProviderClient(context);
+
+  return api.get("/wallet-instances/current/status");
+}