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

package/src/sd-jwt/index.ts

@@ -135,7 +135,7 @@ export const disclose = async (
  *
  *
  * @param token The encoded token that represents a valid sd-jwt for verifiable credentials
- * @param publicKey The public key to validate the signature
+ * @param publicKey The single public key or an array of public keys to validate the signature.
  * @param schema Schema to use to parse the SD-JWT
  *
  * @returns The parsed SD-JWT token and the parsed disclosures
@@ -143,7 +143,7 @@ export const disclose = async (
  */
 export const verify = async <S extends z.AnyZodObject>(
   token: string,
-  publicKey: JWK,
+  publicKey: JWK | JWK[],
   schema: S
 ): Promise<{ sdJwt: z.infer<S>; disclosures: Disclosure[] }> => {
   // get decoded data

package/src/sd-jwt/types.ts

@@ -51,7 +51,7 @@ export const SdJwt4VC = z.object({
     cnf: z.object({
       jwk: JWK,
     }),
-    type: z.literal("PersonIdentificationData"),
+    type: z.string(),
     verified_claims: z.object({
       verification: z.intersection(
         z.object({

package/src/trust/chain.ts

@@ -11,6 +11,7 @@ import { JWK } from "../utils/jwk";
 import { IoWalletError } from "../utils/errors";
 import * as z from "zod";
 import type { JWTDecodeResult } from "@pagopa/io-react-native-jwt/lib/typescript/types";
+import { getSignedEntityConfiguration, getSignedEntityStatement } from ".";
 
 type ParsedToken = {
   header: JWTDecodeResult["protectedHeader"];
@@ -51,12 +52,12 @@ const LastElementShape = z.union([
 /**
  * Validates a provided trust chain against a known trust
  *
- * @param trustAnchorEntity
- * @param chain
+ * @param trustAnchorEntity The entity configuration of the known trust anchor
+ * @param chain The chain of statements to be validate
  * @returns The list of parsed token representing the chain
  * @throws {IoWalletError} If the chain is not valid
  */
-export async function verifyTrustChain(
+export async function validateTrustChain(
   trustAnchorEntity: TrustAnchorEntityConfiguration,
   chain: string[]
 ): Promise<ParsedToken[]> {
@@ -107,3 +108,44 @@ export async function verifyTrustChain(
       .map((args) => verify(...args))
   );
 }
+
+/**
+ * Given a trust chain, obtain a new trust chain by fetching each element's fresh version
+ *
+ * @param chain The original chain
+ * @param appFetch (optional) fetch api implementation
+ * @returns A list of signed token that reprensent the trust chain, in the same order of the provided chain
+ * @throws When an element of the chain fails to parse
+ */
+export function renewTrustChain(
+  chain: string[],
+  appFetch: GlobalFetch["fetch"] = fetch
+) {
+  return Promise.all(
+    chain
+      // Decode each item to determine its shape
+      .map(decode)
+      .map(
+        (e) =>
+          [
+            EntityStatement.safeParse(e),
+            EntityConfiguration.safeParse(e),
+          ] as const
+      )
+      // fetch the element according to its shape
+      .map(([es, ec], i) =>
+        ec.success
+          ? getSignedEntityConfiguration(ec.data.payload.iss, { appFetch })
+          : es.success
+          ? getSignedEntityStatement(es.data.payload.iss, es.data.payload.sub, {
+              appFetch,
+            })
+          : // if the element fail to parse in both EntityStatement and EntityConfiguration, raise an error
+            Promise.reject(
+              new IoWalletError(
+                `Cannot renew trust chain because the element #${i} failed to be parsed.`
+              )
+            )
+      )
+  );
+}

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/errors.ts

@@ -1,3 +1,19 @@
+/**
+ * utility to format a set of attributes into an error message string
+ *
+ * @example
+ * // returns "foo=value bar=(list, item)"
+ * serializeAttrs({ foo: "value", bar: ["list", "item"] })
+ *
+ * @param attrs A key value record set
+ * @returns a human-readable serialization of the set
+ */
+const serializeAttrs = (attrs: Record<string, string | string>): string =>
+  Object.entries(attrs)
+    .map(([k, v]) => [k, Array.isArray(v) ? `(${v.join(", ")})` : v])
+    .map((_) => _.join("="))
+    .join(" ");
+
 /**
  * A generic Error that all other io-wallet specific Error subclasses extend.
  *
@@ -42,8 +58,12 @@ export class ValidationFailed extends IoWalletError {
   /** Reason code for the validation failure. */
   reason: string;
 
-  constructor(message: string, claim = "unspecified", reason = "unspecified") {
-    super(message);
+  constructor(
+    message: string,
+    claim: string = "unspecified",
+    reason: string = "unspecified"
+  ) {
+    super(serializeAttrs({ message, claim, reason }));
     this.claim = claim;
     this.reason = reason;
   }
@@ -66,8 +86,12 @@ export class WalletInstanceAttestationIssuingError extends IoWalletError {
   /** Reason code for the validation failure. */
   reason: string;
 
-  constructor(message: string, claim = "unspecified", reason = "unspecified") {
-    super(message);
+  constructor(
+    message: string,
+    claim: string = "unspecified",
+    reason: string = "unspecified"
+  ) {
+    super(serializeAttrs({ message, claim, reason }));
     this.claim = claim;
     this.reason = reason;
   }
@@ -90,8 +114,12 @@ export class AuthRequestDecodeError extends IoWalletError {
   /** Reason code for the validation failure. */
   reason: string;
 
-  constructor(message: string, claim = "unspecified", reason = "unspecified") {
-    super(message);
+  constructor(
+    message: string,
+    claim: string = "unspecified",
+    reason: string = "unspecified"
+  ) {
+    super(serializeAttrs({ message, claim, reason }));
     this.claim = claim;
     this.reason = reason;
   }
@@ -114,8 +142,12 @@ export class PidIssuingError extends IoWalletError {
   /** Reason code for the validation failure. */
   reason: string;
 
-  constructor(message: string, claim = "unspecified", reason = "unspecified") {
-    super(message);
+  constructor(
+    message: string,
+    claim: string = "unspecified",
+    reason: string = "unspecified"
+  ) {
+    super(serializeAttrs({ message, claim, reason }));
     this.claim = claim;
     this.reason = reason;
   }

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