@pagopa/io-react-native-wallet 0.7.4 → 0.9.0

package/src/trust/index.ts

@@ -5,11 +5,74 @@ import {
   CredentialIssuerEntityConfiguration,
   RelyingPartyEntityConfiguration,
   EntityConfiguration,
+  EntityStatement,
 } from "./types";
-import { IoWalletError } from "../utils/errors";
-import { verifyTrustChain } from "./chain";
+import { validateTrustChain, renewTrustChain } from "./chain";
+import { hasStatus } from "../utils/misc";
 
-export { verifyTrustChain };
+export type {
+  WalletProviderEntityConfiguration,
+  TrustAnchorEntityConfiguration,
+  CredentialIssuerEntityConfiguration,
+  RelyingPartyEntityConfiguration,
+  EntityConfiguration,
+  EntityStatement,
+};
+
+/**
+ * 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 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
+ * @returns The result of the chain validation
+ * @throws {IoWalletError} When either validation or renewal fail
+ */
+export async function verifyTrustChain(
+  trustAnchorEntity: TrustAnchorEntityConfiguration,
+  chain: string[],
+  {
+    appFetch = fetch,
+    renewOnFail = true,
+  }: { appFetch?: GlobalFetch["fetch"]; renewOnFail?: boolean } = {}
+): Promise<ReturnType<typeof validateTrustChain>> {
+  try {
+    return validateTrustChain(trustAnchorEntity, chain);
+  } catch (error) {
+    if (renewOnFail) {
+      const renewedChain = await renewTrustChain(chain, appFetch);
+      return validateTrustChain(trustAnchorEntity, renewedChain);
+    } else {
+      throw error;
+    }
+  }
+}
+
+/**
+ * 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
+ * @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(hasStatus(200))
+    .then((res) => res.text());
+}
 
 /**
  * Fetch and parse the entity configuration document for a given federation entity.
@@ -77,24 +140,15 @@ async function fetchAndParseEntityConfiguration(
     appFetch?: GlobalFetch["fetch"];
   } = {}
 ) {
-  const wellKnownUrl = `${entityBaseUrl}/.well-known/openid-federation`;
-
-  const response = await appFetch(wellKnownUrl, {
-    method: "GET",
+  const responseText = await getSignedEntityConfiguration(entityBaseUrl, {
+    appFetch,
   });
 
-  if (response.status === 200) {
-    const responseText = await response.text();
-    const responseJwt = decodeJwt(responseText);
-    return schema.parse({
-      header: responseJwt.protectedHeader,
-      payload: responseJwt.payload,
-    });
-  }
-
-  throw new IoWalletError(
-    `Unable to obtain Entity Configuration at ${wellKnownUrl}. Response code: ${response.status}`
-  );
+  const responseJwt = decodeJwt(responseText);
+  return schema.parse({
+    header: responseJwt.protectedHeader,
+    payload: responseJwt.payload,
+  });
 }
 
 export const getWalletProviderEntityConfiguration = (
@@ -142,3 +196,66 @@ export const getEntityConfiguration = (
   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 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 parsed entity configuration object
+ * @throws {IoWalletError} If the http request fails
+ * @throws Parse error if the document is not in the expected shape.
+ */
+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 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
+ */
+export async function getSignedEntityStatement(
+  accreditationBodyBaseUrl: string,
+  subordinatedEntityBaseUrl: string,
+  {
+    appFetch = fetch,
+  }: {
+    appFetch?: GlobalFetch["fetch"];
+  } = {}
+) {
+  const url = `${accreditationBodyBaseUrl}/fetch?${new URLSearchParams({
+    sub: subordinatedEntityBaseUrl,
+  })}`;
+
+  return await appFetch(url, {
+    method: "GET",
+  })
+    .then(hasStatus(200))
+    .then((res) => res.text());
+}

package/src/trust/types.ts

@@ -5,6 +5,15 @@ import * as z from "zod";
 export const TrustMark = z.object({ id: z.string(), trust_mark: z.string() });
 export type TrustMark = z.infer<typeof TrustMark>;
 
+const RelyingPartyMetadata = z.object({
+  application_type: z.string().optional(),
+  client_id: z.string().optional(),
+  client_name: z.string().optional(),
+  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
 type CredentialDisplayMetadata = z.infer<typeof CredentialDisplayMetadata>;
@@ -19,13 +28,28 @@ const CredentialDisplayMetadata = z.object({
   text_color: z.string(),
 });
 
+type CredentialDefinitionMetadata = z.infer<
+  typeof CredentialDefinitionMetadata
+>;
+const CredentialDefinitionMetadata = z.object({
+  type: z.array(z.string()),
+  credentialSubject: z.record(
+    z.object({
+      mandatory: z.boolean(),
+      display: z.array(z.object({ name: z.string(), locale: z.string() })),
+    })
+  ),
+});
+
 // Metadata for a credentia which i supported by a Issuer
 type SupportedCredentialMetadata = z.infer<typeof SupportedCredentialMetadata>;
 const SupportedCredentialMetadata = z.object({
+  id: z.string(),
   format: z.literal("vc+sd-jwt"),
   cryptographic_binding_methods_supported: z.array(z.string()),
   cryptographic_suites_supported: z.array(z.string()),
   display: z.array(CredentialDisplayMetadata),
+  credential_definition: CredentialDefinitionMetadata,
 });
 
 export type EntityStatement = z.infer<typeof EntityStatement>;
@@ -54,6 +78,20 @@ export const EntityConfigurationHeader = z.object({
   kid: z.string(),
 });
 
+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(),
+    homepage_uri: z.string().optional(),
+    policy_uri: z.string().optional(),
+    logo_uri: z.string().optional(),
+    contacts: z.array(z.string()).optional(),
+  })
+  .passthrough();
+
 // Structuire common to every Entity Configuration document
 const BaseEntityConfiguration = z.object({
   header: EntityConfigurationHeader,
@@ -68,19 +106,7 @@ const BaseEntityConfiguration = z.object({
       }),
       metadata: z
         .object({
-          federation_entity: 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(),
-              homepage_uri: z.string().optional(),
-              policy_uri: z.string().optional(),
-              logo_uri: z.string().optional(),
-              contacts: z.array(z.string()).optional(),
-            })
-            .passthrough(),
+          federation_entity: FederationEntityMetadata,
         })
         .passthrough(),
       authority_hints: z.array(z.string()).optional(),
@@ -113,6 +139,24 @@ export const CredentialIssuerEntityConfiguration = BaseEntityConfiguration.and(
           credentials_supported: z.array(SupportedCredentialMetadata),
           jwks: z.object({ keys: z.array(JWK) }),
         }),
+        /** Credential Issuers act as Relying Party 
+            when they require the presentation of other credentials.
+            This does not apply for PID issuance, which requires CIE authz. */
+        wallet_relying_party: RelyingPartyMetadata.optional(),
+      }),
+    }),
+  })
+);
+
+// Entity configuration for a Relying Party
+export type RelyingPartyEntityConfiguration = z.infer<
+  typeof RelyingPartyEntityConfiguration
+>;
+export const RelyingPartyEntityConfiguration = BaseEntityConfiguration.and(
+  z.object({
+    payload: z.object({
+      metadata: z.object({
+        wallet_relying_party: RelyingPartyMetadata,
       }),
     }),
   })
@@ -145,28 +189,6 @@ export const WalletProviderEntityConfiguration = BaseEntityConfiguration.and(
   })
 );
 
-// Entity configuration for a Relying Party
-export type RelyingPartyEntityConfiguration = z.infer<
-  typeof RelyingPartyEntityConfiguration
->;
-export const RelyingPartyEntityConfiguration = BaseEntityConfiguration.and(
-  z.object({
-    payload: z.object({
-      metadata: z.object({
-        wallet_relying_party: z
-          .object({
-            application_type: z.string().optional(),
-            client_id: z.string().optional(),
-            client_name: z.string().optional(),
-            jwks: z.object({ keys: z.array(JWK) }),
-            contacts: z.array(z.string()).optional(),
-          })
-          .passthrough(),
-      }),
-    }),
-  })
-);
-
 // Maps any entity configuration by the union of every possible shapes
 export type EntityConfiguration = z.infer<typeof EntityConfiguration>;
 export const EntityConfiguration = z.union(

package/src/utils/crypto.ts

@@ -46,24 +46,6 @@ export const createCryptoContextFor = (keytag: string): CryptoContext => {
   };
 };
 
-// Wraps finally for async expressions
-const asyncFinally =
-  <A extends Array<unknown>, R>(
-    fn: (...args: A) => Promise<R>,
-    onFinally: () => void | Promise<void>
-  ) =>
-  async (...args: A): Promise<R> => {
-    try {
-      return await fn(...args);
-      //     ^^^^^ return await is usually to be avoided,
-      //           in this case is needed for the finally{} statement to be executed correctly
-    } catch (error) {
-      throw error;
-    } finally {
-      await onFinally();
-    }
-  };
-
 /**
  * Executes the input function injecting an ephemeral crypto context.
  * An ephemeral crypto context is a context which is bound to a key
@@ -72,12 +54,12 @@ const asyncFinally =
  * @param fn The procedure to be executed
  * @returns The returned value of the input procedure.
  */
-export const useEphemeralKey = async <R>(
+export const withEphemeralKey = async <R>(
   fn: (ephemeralContext: CryptoContext) => Promise<R>
 ): Promise<R> => {
   // Use an ephemeral key to be destroyed after use
   const keytag = `ephemeral-${uuid.v4()}`;
   await generate(keytag);
   const ephemeralContext = createCryptoContextFor(keytag);
-  return asyncFinally(fn, () => deleteKey(keytag))(ephemeralContext);
+  return fn(ephemeralContext).finally(() => deleteKey(keytag));
 };

package/src/utils/misc.ts

@@ -0,0 +1,23 @@
+import { IoWalletError } from "./errors";
+
+/**
+ * Check if a response is in the expected status, other
+ * @param status The expected status
+ * @returns The given response object
+ */
+export const hasStatus =
+  (status: number) =>
+  (res: Response): Response => {
+    if (res.status !== status) {
+      throw new IoWalletError(
+        `Http request failed. Expected ${status}, got ${res.status}, url: ${res.url}`
+      );
+    }
+    return res;
+  };
+
+// extract a type from an async function output
+// helpful to bind the input of a function to the output of another
+export type Out<FN> = FN extends (...args: any[]) => Promise<any>
+  ? Awaited<ReturnType<FN>>
+  : never;

package/src/utils/par.ts

@@ -0,0 +1,103 @@
+import {
+  sha256ToBase64,
+  type CryptoContext,
+  SignJWT,
+} from "@pagopa/io-react-native-jwt";
+import uuid from "react-native-uuid";
+import * as z from "zod";
+import * as WalletInstanceAttestation from "../wallet-instance-attestation";
+import { hasStatus } from "./misc";
+
+export type AuthorizationDetail = z.infer<typeof AuthorizationDetail>;
+export const AuthorizationDetail = z.object({
+  credential_definition: z.object({
+    type: z.string(),
+  }),
+  format: z.literal("vc+sd-jwt"),
+  type: z.literal("openid_credential"),
+});
+
+export type AuthorizationDetails = z.infer<typeof AuthorizationDetails>;
+export const AuthorizationDetails = z.array(AuthorizationDetail);
+
+/**
+ * Make a PAR request to the issuer and return the response url
+ */
+export const makeParRequest =
+  ({
+    wiaCryptoContext,
+    appFetch = fetch,
+  }: {
+    wiaCryptoContext: CryptoContext;
+    appFetch?: GlobalFetch["fetch"];
+  }) =>
+  async (
+    clientId: string,
+    codeVerifier: string,
+    walletProviderBaseUrl: string,
+    parEndpoint: string,
+    walletInstanceAttestation: string,
+    authorizationDetails: AuthorizationDetails,
+    assertionType: string
+  ): Promise<string> => {
+    const wiaPublicKey = await wiaCryptoContext.getPublicKey();
+
+    const parUrl = new URL(parEndpoint);
+    const aud = `${parUrl.protocol}//${parUrl.hostname}`;
+
+    const iss = WalletInstanceAttestation.decode(walletInstanceAttestation)
+      .payload.cnf.jwk.kid;
+
+    /** A code challenge is provided so that the PAR is bound 
+        to the subsequent authorization code request
+        @see https://datatracker.ietf.org/doc/html/rfc9126#name-request */
+    const codeChallengeMethod = "s256";
+    const codeChallenge = await sha256ToBase64(codeVerifier);
+
+    /** The PAR request token is signed used the Wallet Instance Attestation key.
+        The signature can be verified by reading the public key from the key set shippet
+        with the it will ship the Wallet Instance Attestation.
+        The key is matched by its kid */
+    const signedJwtForPar = await new SignJWT(wiaCryptoContext)
+      .setProtectedHeader({
+        kid: wiaPublicKey.kid,
+      })
+      .setPayload({
+        iss,
+        aud,
+        jti: `${uuid.v4()}`,
+        client_assertion_type: assertionType,
+        authorization_details: authorizationDetails,
+        response_type: "code",
+        redirect_uri: walletProviderBaseUrl,
+        state: `${uuid.v4()}`,
+        client_id: clientId,
+        code_challenge_method: codeChallengeMethod,
+        code_challenge: codeChallenge,
+      })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign();
+
+    /** The request body for the Pushed Authorization Request */
+    var formBody = new URLSearchParams({
+      response_type: "code",
+      client_id: clientId,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256",
+      client_assertion_type: assertionType,
+      client_assertion: walletInstanceAttestation,
+      request: signedJwtForPar,
+    });
+
+    return await appFetch(parEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: formBody.toString(),
+    })
+      .then(hasStatus(201))
+      .then((res) => res.json())
+      .then((result) => result.request_uri);
+  };