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

package/src/trust/v1.3.3/types.ts

@@ -0,0 +1,68 @@
+import * as z from "zod";
+import { JWK } from "../../utils/jwk";
+import { BaseEntityConfiguration } from "../common/types";
+import {
+  itWalletCredentialIssuerMetadataV1_3,
+  itWalletAuthorizationServerMetadataV1_3,
+  itWalletSolutionEntityMetadataV1_3,
+  itWalletCredentialVerifierMetadataV1_3,
+} from "@pagopa/io-wallet-oid-federation";
+
+// Entity configuration for a Credential Issuer
+export type CredentialIssuerEntityConfiguration = z.infer<
+  typeof CredentialIssuerEntityConfiguration
+>;
+export const CredentialIssuerEntityConfiguration = BaseEntityConfiguration.and(
+  z.object({
+    payload: z.object({
+      jwks: z.object({ keys: z.array(JWK) }),
+      metadata: z.object({
+        openid_credential_issuer: itWalletCredentialIssuerMetadataV1_3,
+        oauth_authorization_server: itWalletAuthorizationServerMetadataV1_3,
+        openid_credential_verifier:
+          itWalletCredentialVerifierMetadataV1_3.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({
+        openid_credential_verifier: itWalletCredentialVerifierMetadataV1_3,
+      }),
+    }),
+  })
+);
+
+// Entity configuration for a Wallet Provider
+export type WalletProviderEntityConfiguration = z.infer<
+  typeof WalletProviderEntityConfiguration
+>;
+export const WalletProviderEntityConfiguration = BaseEntityConfiguration.and(
+  z.object({
+    payload: z.object({
+      metadata: z.object({
+        wallet_solution: itWalletSolutionEntityMetadataV1_3,
+      }),
+    }),
+  })
+);
+
+// Maps any entity configuration by the union of every possible shapes
+export type EntityConfiguration = z.infer<typeof EntityConfiguration>;
+export const EntityConfiguration = z.union(
+  [
+    WalletProviderEntityConfiguration,
+    CredentialIssuerEntityConfiguration,
+    RelyingPartyEntityConfiguration,
+  ],
+  {
+    description: "Any kind of Entity Configuration allowed in the ecosystem",
+  }
+);

package/src/utils/callbacks.ts

@@ -0,0 +1,84 @@
+import { EncryptJwe, getJwkFromHeader } from "@pagopa/io-react-native-jwt";
+import { verify } from "@pagopa/io-react-native-jwt";
+import { type CallbackContext } from "@pagopa/io-wallet-oauth2";
+import { digest } from "@sd-jwt/crypto-nodejs";
+import { X509 } from "jsrsasign";
+import { IoWalletError } from "./errors";
+import { generateRandomBytes } from "./misc";
+import type { JWK } from "./jwk";
+
+type PartialCallbackContext = Omit<
+  CallbackContext,
+  "signJwt" | "clientAuthentication"
+>;
+
+/**
+ * Shared callbacks with React Native implementations for use
+ * in IO Wallet SDK. Callbacks not found here must be provided by the caller,
+ * as they require parameters that depends on the use case.
+ */
+export const partialCallbacks: PartialCallbackContext = {
+  generateRandom: generateRandomBytes,
+  hash: digest,
+  encryptJwe: async ({ publicJwk, alg, enc, kid }, data) => ({
+    // @ts-expect-error `alg` and `enc` are strings, but EncryptJwe expects specific string literals
+    jwe: await new EncryptJwe(data, { alg, enc, kid }).encrypt(publicJwk),
+    encryptionJwk: publicJwk,
+  }),
+  verifyJwt: async (jwtSigner, jwt) => {
+    // TODO: support other signing methods if needed
+    if (jwtSigner.method !== "jwk") {
+      throw new IoWalletError(`Unsupported signer method: ${jwtSigner.method}`);
+    }
+    try {
+      await verify(jwt.compact, jwtSigner.publicJwk);
+      return { verified: true, signerJwk: jwtSigner.publicJwk };
+    } catch {
+      return { verified: false };
+    }
+  },
+  decryptJwe: () => {
+    throw new IoWalletError("decryptJwe is not implemented");
+  },
+  getX509CertificateMetadata: (certificate) => {
+    const x509 = new X509();
+    x509.readCertPEM(certificate);
+    const sanExt = x509.getExtSubjectAltName(certificate);
+
+    const sanDnsNames: string[] = [];
+    const sanUriNames: string[] = [];
+
+    for (const item of sanExt.array) {
+      if (!item) continue;
+      if ("dns" in item) sanDnsNames.push(item.dns);
+      if ("uri" in item) sanUriNames.push(item.uri);
+    }
+
+    return { sanDnsNames, sanUriNames };
+  },
+};
+
+type JWSHeader = Parameters<typeof getJwkFromHeader>[0];
+
+/**
+ * Create a verifyJwt implementation that extracts the JWK for signature verification
+ * from a list of keys, matching the `kid` in the JWT header.
+ *
+ * This function does not support other `JwtSigner` methods.
+ *
+ * @param jwks The list of available keys
+ * @returns Function that implements `verifyJwt` callback
+ */
+export const createVerifyJwtFromJwks = (
+  jwks: JWK[]
+): CallbackContext["verifyJwt"] => {
+  return async function verifyJwt(_, jwt) {
+    try {
+      const signerJwk = getJwkFromHeader(jwt.header as JWSHeader, jwks);
+      await verify(jwt.compact, signerJwk);
+      return { verified: true, signerJwk };
+    } catch {
+      return { verified: false };
+    }
+  };
+};

package/src/utils/config.ts

@@ -0,0 +1,18 @@
+import {
+  IoWalletSdkConfig,
+  ItWalletSpecsVersion,
+} from "@pagopa/io-wallet-utils";
+
+/**
+ * IO Wallet SDK configuration object for v1.0 specs.
+ */
+export const sdkConfigV1_0 = new IoWalletSdkConfig({
+  itWalletSpecsVersion: ItWalletSpecsVersion.V1_0,
+});
+
+/**
+ * IO Wallet SDK configuration object for v1.3 specs.
+ */
+export const sdkConfigV1_3 = new IoWalletSdkConfig({
+  itWalletSpecsVersion: ItWalletSpecsVersion.V1_3,
+});

package/src/utils/credentials.ts

@@ -1,11 +1,12 @@
-import { decode } from "../sd-jwt";
+import { decodeSdJwtSync } from "@sd-jwt/decode";
+import { digest } from "@sd-jwt/crypto-nodejs";
 import { thumbprint } from "@pagopa/io-react-native-jwt";
-import type { Out } from "./misc";
-import type { ObtainCredential } from "../credential/issuance";
+import type { CredentialFormat } from "../credential/issuance";
 import type { JWK } from "./jwk";
 import { IoWalletError } from "./errors";
 import {
   LEGACY_SD_JWT,
+  SdJwt4VCBase,
   type SupportedSdJwtLegacyFormat,
 } from "../sd-jwt/types";
 
@@ -18,15 +19,15 @@ const SD_JWT = ["dc+sd-jwt", LEGACY_SD_JWT];
  * @return A Promise that resolves to a JWK object if the credential is in SD-JWT format and contains a JWK, or undefined otherwise.
  */
 export const extractJwkFromCredential = async (
-  credential: Out<ObtainCredential>["credential"],
-  format: Out<ObtainCredential>["format"] | SupportedSdJwtLegacyFormat
+  credential: string,
+  format: CredentialFormat | SupportedSdJwtLegacyFormat
 ): Promise<JWK> => {
   if (SD_JWT.includes(format)) {
     // 1. SD-JWT case
-    const decoded = decode(credential);
-    const jwk = decoded.sdJwt.payload.cnf.jwk;
-    if (jwk) {
-      return { ...jwk, kid: await thumbprint(jwk) };
+    const decoded = decodeSdJwtSync(credential, digest);
+    const { cnf } = decoded.jwt.payload as SdJwt4VCBase["payload"];
+    if (cnf.jwk) {
+      return { ...cnf.jwk, kid: await thumbprint(cnf.jwk) };
     }
   }
   throw new IoWalletError(`Credential format ${format} not supported`);

package/src/utils/errors.ts

@@ -1,4 +1,6 @@
-import type { ProblemDetail } from "../client/generated/wallet-provider";
+import { UnexpectedStatusCodeError as SdkUnexpectedStatusCodeError } from "@pagopa/io-wallet-utils";
+import type { ProblemJson } from "../client/generated/wallet-provider";
+import type { IssuerConfig } from "../credential/issuance/api";
 import {
   type IssuerResponseErrorCode,
   IssuerResponseErrorCodes,
@@ -7,7 +9,6 @@ import {
   type WalletProviderResponseErrorCode,
   WalletProviderResponseErrorCodes,
 } from "./error-codes";
-import type { CredentialIssuerEntityConfiguration } from "../trust/types";
 
 export {
   IssuerResponseErrorCodes,
@@ -41,6 +42,37 @@ export const serializeAttrs = (
     .map((_) => _.join("="))
     .join(" ");
 
+/**
+ * Wraps a synchronous function and maps a specific error type to a library error.
+ *
+ * @param fn - The function to execute
+ * @param sourceError - The error class constructor to catch
+ * @param mapError - Function to map the caught error to a library error
+ * @returns The result of the function if it succeeds
+ * @throws The mapped error if sourceError is caught, or the original error otherwise
+ *
+ * @example
+ * const result = withMappedErrors(
+ *   () => sdkExtractGrantDetails(offer),
+ *   CredentialOfferError,
+ *   (e) => new InvalidCredentialOfferError(e.message)
+ * );
+ */
+export const withMappedErrors = <T, E extends Error>(
+  fn: () => T,
+  sourceError: new (...args: any[]) => E,
+  mapError: (error: E) => Error
+): T => {
+  try {
+    return fn();
+  } catch (e) {
+    if (e instanceof sourceError) {
+      throw mapError(e);
+    }
+    throw e;
+  }
+};
+
 /**
  * A generic Error that all other io-wallet specific Error subclasses extend.
  *
@@ -137,12 +169,12 @@ export class IssuerResponseError extends UnexpectedStatusCodeError {
  */
 export class WalletProviderResponseError extends UnexpectedStatusCodeError {
   code: WalletProviderResponseErrorCode;
-  reason: ProblemDetail;
+  reason: ProblemJson;
 
   constructor(params: {
     code?: WalletProviderResponseErrorCode;
     message: string;
-    reason: ProblemDetail;
+    reason: ProblemJson;
     statusCode: number;
   }) {
     super(params);
@@ -193,14 +225,12 @@ export function extractErrorMessageFromIssuerConf(
     issuerConf,
     credentialType,
   }: {
-    issuerConf: CredentialIssuerEntityConfiguration["payload"]["metadata"];
+    issuerConf: IssuerConfig;
     credentialType: string;
   }
 ): LocalizedIssuanceError | undefined {
   const credentialConfiguration =
-    issuerConf.openid_credential_issuer.credential_configurations_supported[
-      credentialType
-    ];
+    issuerConf.credential_configurations_supported[credentialType];
 
   if (!credentialConfiguration) {
     throw new IoWalletError(
@@ -269,7 +299,7 @@ type ErrorCase<T> = {
  *
  * Chain multiple `handle` to add cases that depend on the status code, then call `buildFrom` when done.
  *
- * For example:
+ * @example
  * ```
  * new ResponseErrorBuilder(IssuerResponseError)
  *   .handle(403, { code: "ERROR_CODE_1", message: "Forbidden" })
@@ -301,3 +331,36 @@ export class ResponseErrorBuilder<T extends typeof UnexpectedStatusCodeError> {
     return originalError;
   }
 }
+
+/**
+ * Error thrown when the library does not implement
+ * a feature aligned with the specified version.
+ */
+export class UnimplementedFeatureError extends IoWalletError {
+  code = "ERR_IO_WALLET_UNIMPLEMENTED_FEATURE";
+
+  constructor(feature: string, version: string) {
+    super(`Missing v${version} compatible implementation for ${feature}`);
+  }
+}
+
+/**
+ * Map `UnexpectedStatusCodeError` thrown from IO Wallet SDK to `IssuerResponseError`.
+ * Use this function in catch blocks.
+ * @param err The original error
+ * @throws Generic {@link IssuerResponseError}
+ * @throws The original error if it doesn't match
+ * @example
+ * await fetchAuthorizationRequest().catch(sdkUnexpectedStatusCodeToIssuerError)
+ */
+export const sdkUnexpectedStatusCodeToIssuerError = (err: unknown) => {
+  if (err instanceof SdkUnexpectedStatusCodeError) {
+    throw new IssuerResponseError({
+      code: IssuerResponseErrorCodes.IssuerGenericError,
+      message: err.message,
+      reason: err.reason,
+      statusCode: err.statusCode,
+    });
+  }
+  throw err;
+};

package/src/utils/mappers.ts

@@ -0,0 +1,84 @@
+import * as z from "zod";
+
+/**
+ * Create a mapper to convert data from type I to type O.
+ *
+ * By default only static type checking is applied when mapping types.
+ * To include runtime validation, provide zod schemas for I (optional) and O.
+ *
+ * @param mapper The mapping function
+ * @param config.inputSchema The schema to validate the input before mapping (optional)
+ * @param config.outputSchema The schema to validate the mapped input (required when config is provided)
+ * @returns A function to convert I to O
+ *
+ * @example
+ * // Type checking only
+ * createMapper<TypeA, TypeB>(mapper)
+ *
+ * // Type checking with runtime validation
+ * createMapper(mapper, {
+ *   inputSchema: TypeA,
+ *   outputSchema: TypeB
+ * })
+ */
+export function createMapper<I, O>(mapper: (input: I) => O): (input: I) => O;
+export function createMapper<I, O>(
+  mapper: (input: I) => O,
+  config: { inputSchema: z.ZodType<I>; outputSchema: z.ZodType<O> }
+): (input: unknown) => O;
+export function createMapper<I, O>(
+  mapper: (input: I) => O,
+  config: { outputSchema: z.ZodType<O> }
+): (input: I) => O;
+export function createMapper<I, O>(
+  mapper: (input: I) => O,
+  config?: {
+    inputSchema?: z.ZodType<I>;
+    outputSchema: z.ZodType<O>;
+  }
+) {
+  if (!config) {
+    return mapper;
+  }
+
+  const { inputSchema, outputSchema } = config;
+
+  if (inputSchema) {
+    return (input: unknown) =>
+      inputSchema.transform(mapper).pipe(outputSchema).parse(input);
+  }
+
+  return (input: I) => outputSchema.parse(mapper(input));
+}
+
+/**
+ * Higher order function to pipe a function return value to the provided mapper.
+ * Supports only synchronous functions. Use {@link withMapperAsync} for async ones.
+ * @param mapper The mapping function
+ * @fn The function to wrap
+ * @return The original function with the mapper applied to its return value
+ */
+export const withMapper = <A extends any[], I, O>(
+  mapper: (input: I) => O,
+  fn: (...args: A) => I
+) => {
+  return function wrappedFunction(...args: A) {
+    return mapper(fn(...args));
+  };
+};
+
+/**
+ * Higher order function to pipe an async function return value to the provided mapper.
+ * Supports only asynchronous functions. Use {@link withMapper} for sync ones.
+ * @param mapper The mapping function
+ * @fn The function to wrap
+ * @return The original function with the mapper applied to its return value
+ */
+export const withMapperAsync = <A extends any[], I, O>(
+  mapper: (input: I) => O,
+  fn: (...args: A) => Promise<I>
+) => {
+  return async function wrappedAsyncFunction(...args: A) {
+    return mapper(await fn(...args));
+  };
+};

package/src/utils/misc.ts

@@ -55,6 +55,14 @@ export const generateRandomAlphaNumericString = (size: number) =>
     Math.floor(Math.random() * 36).toString(36)
   ).join("");
 
+/**
+ * TODO [SIW-1310]: replace this function with a cryptographically secure one.
+ * @param size - The size of the array in bytes
+ * @returns An array of the given size filled with random bytes
+ */
+export const generateRandomBytes = (size: number) =>
+  Uint8Array.from({ length: size }, () => Math.floor(Math.random() * 256));
+
 /**
  * Get the hash of a credential without discloures.
  * A credential is a string like `header.body.sign~sd1~sd2....` where `~` is the separator between the credential and the discloures.
@@ -79,5 +87,11 @@ export const safeJsonParse = <T>(text: string, withDefault?: T): T | null => {
   }
 };
 
-export const isObject = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
+export function assert(
+  condition: unknown,
+  msg: string = "Assertion failed"
+): asserts condition {
+  if (!condition) {
+    throw new IoWalletError(msg);
+  }
+}

package/src/utils/object.ts

@@ -0,0 +1,15 @@
+export const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+export const keyBy = <T, K extends keyof T>(array: T[], key: K) =>
+  array.reduce((acc, item) => {
+    acc.set(item[key], item);
+    return acc;
+  }, new Map<T[K], T>());
+
+export const groupBy = <T, K extends keyof T>(array: T[], key: K) =>
+  array.reduce((acc, item) => {
+    const k = item[key];
+    acc.set(k, [...(acc.get(k) ?? []), item]);
+    return acc;
+  }, new Map<T[K], T[]>());

package/src/utils/par.ts

@@ -5,7 +5,6 @@ import {
 } from "@pagopa/io-react-native-jwt";
 import { v4 as uuidv4 } from "uuid";
 import * as z from "zod";
-import * as WalletInstanceAttestation from "../wallet-instance-attestation";
 import { generateRandomAlphaNumericString, hasStatusOrThrow } from "./misc";
 import { createPopToken } from "./pop";
 import { IssuerResponseError } from "./errors";
@@ -72,14 +71,13 @@ export const makeParRequest =
   ): Promise<string> => {
     const wiaPublicKey = await wiaCryptoContext.getPublicKey();
 
-    const iss = WalletInstanceAttestation.decode(walletInstanceAttestation)
-      .payload.cnf.jwk.kid;
+    // const iss = WalletInstanceAttestation.decode(walletInstanceAttestation).payload.cnf.jwk.kid;
 
     const signedWiaPoP = await createPopToken(
       {
         jti: `${uuidv4()}`,
         aud,
-        iss,
+        iss: clientId,
       },
       wiaCryptoContext
     );
@@ -105,7 +103,7 @@ export const makeParRequest =
         response_type: "code",
         response_mode: responseMode,
         client_id: clientId,
-        iss,
+        iss: clientId,
         state: generateRandomAlphaNumericString(32),
         code_challenge: codeChallenge,
         code_challenge_method: codeChallengeMethod,

package/src/utils/zod.ts

@@ -26,3 +26,6 @@ export const stringToJSONSchema = z
       return z.NEVER;
     }
   });
+
+export const UnixTime = z.number().min(0).max(2147483647000);
+export type UnixTime = z.infer<typeof UnixTime>;

package/src/wallet-instance/README.md

@@ -14,6 +14,7 @@ Examples are provided as follows:
 ### Wallet instance creation
 
 ```ts
+const wallet = new IoWallet({ version: "1.0.0" });
 // Get env
 const { GOOGLE_CLOUD_PROJECT_NUMBER, WALLET_PROVIDER_BASE_URL } = env; // Let's assume env is an object containing the environment variables
 
@@ -25,7 +26,7 @@ await ensureIntegrityServiceIsReady(googleCloudProjectNumber); // Required by io
 const integrityKeyTag = await generateIntegrityHardwareKeyTag();
 const integrityContext = getIntegrityContext(integrityKeyTag); // This function is supposed to return an object as required by IntegrityContext.
 
-await WalletInstance.createWalletInstance({
+await wallet.WalletInstance.createWalletInstance({
   integrityContext,
   walletProviderBaseUrl: WALLET_PROVIDER_BASE_URL,
   appFetch,
@@ -41,10 +42,11 @@ The returned `integrityKeyTag` is supposed to be stored and used to verify the i
 Revoke a Wallet Instance by ID. The ID matches the hardware/integrity key tag used for creation.
 
 ```ts
+const wallet = new IoWallet({ version: "1.0.0" });
 const { WALLET_PROVIDER_BASE_URL } = env;
 
-await WalletInstance.revokeWalletInstance({
-  id: "495e5bec-b93f-4fd7-952a-94b27233abdb"
+await wallet.WalletInstance.revokeWalletInstance({
+  id: "495e5bec-b93f-4fd7-952a-94b27233abdb",
   walletProviderBaseUrl: WALLET_PROVIDER_BASE_URL,
   appFetch,
 });
@@ -55,10 +57,11 @@ await WalletInstance.revokeWalletInstance({
 Get the status of a Wallet Instance by ID. The ID matches the hardware/integrity key tag used for creation.
 
 ```ts
+const wallet = new IoWallet({ version: "1.0.0" });
 const { WALLET_PROVIDER_BASE_URL } = env;
 
-const status = await WalletInstance.getWalletInstanceStatus({
-  id: "495e5bec-b93f-4fd7-952a-94b27233abdb"
+const status = await wallet.WalletInstance.getWalletInstanceStatus({
+  id: "495e5bec-b93f-4fd7-952a-94b27233abdb",
   walletProviderBaseUrl: WALLET_PROVIDER_BASE_URL,
   appFetch,
 });

package/src/wallet-instance/api/index.ts

@@ -0,0 +1,53 @@
+import type { IntegrityContext } from "../../utils/integrity";
+
+export type WalletInstanceStatus = {
+  id: string;
+  is_revoked: boolean;
+  revocation_reason?:
+    | "CERTIFICATE_REVOKED_BY_ISSUER"
+    | "NEW_WALLET_INSTANCE_CREATED"
+    | "WALLET_INSTANCE_RENEWAL"
+    | "REVOKED_BY_USER";
+};
+
+export interface WalletInstanceApi {
+  /**
+   * Create a new Wallet Instance.
+   */
+  createWalletInstance(context: {
+    integrityContext: IntegrityContext;
+    walletProviderBaseUrl: string;
+    isRenewal?: boolean;
+    appFetch?: GlobalFetch["fetch"];
+  }): Promise<string>;
+
+  /**
+   * Revoke a Wallet Instance by ID.
+   * @param context.id The Wallet Instance ID. It matches the hardware key tag used for creation.
+   */
+  revokeWalletInstance(context: {
+    id: string;
+    walletProviderBaseUrl: string;
+    appFetch?: GlobalFetch["fetch"];
+  }): Promise<void>;
+
+  /**
+   * Get the status of a Wallet Instance by ID.
+   * @param context.id The Wallet Instance ID. It matches the hardware key tag used for creation.
+   * @returns Details on the status of the Wallet Instance
+   */
+  getWalletInstanceStatus(context: {
+    id: string;
+    walletProviderBaseUrl: string;
+    appFetch?: GlobalFetch["fetch"];
+  }): Promise<WalletInstanceStatus>;
+
+  /**
+   * Get the status of the current Wallet Instance.
+   * @returns Details on the status of the current Wallet Instance
+   */
+  getCurrentWalletInstanceStatus(context: {
+    walletProviderBaseUrl: string;
+    appFetch?: GlobalFetch["fetch"];
+  }): Promise<WalletInstanceStatus>;
+}