@pagopa/io-react-native-wallet 3.0.1 → 3.1.0

package/src/wallet-unit-attestation/README.md

@@ -0,0 +1,73 @@
+# Wallet Unit Attestation
+
+This flow is used to obtain a [**Wallet Unit Attestation**](https://italia.github.io/eid-wallet-it-docs/releases/1.3.3/en/wallet-solution-requirements.html#wallet-unit-attestation-requirements). The WUA is bound to one or more cryptographic keys, that must be provided by the consumer application:
+- `keyAttestationCryptoContext` one or more objects that extend the `CryptoContext` with a function to generate a WSCD-stored key with an optional key attestation (Android only); these are the keys that will be attested in the WUA.
+- `integrityContext` object that is used to verify the integrity of the device where the app is running. The key tag must be the same used when creating the Wallet Instance.
+
+#### Note
+Before invoking `WalletUnitAttestation`'s functions, it is necessary to check whether the feature is supported by the current IoWallet instance.
+```ts
+const wallet = new IoWallet({ version: "1.3.3" });
+
+if (wallet.WalletUnitAttestation.isSupported) {
+  // Get the WUA
+}
+```
+
+### Example usage
+
+```ts
+import {
+  IoWallet,
+  createCryptoContextFor,
+  KeyAttestationCryptoContext
+} from "@pagopa/io-react-native-wallet";
+
+// Retrieve the integrity key tag from the store and create its context
+const integrityKeyTag = "example"; // Let's assume this is the same key used when creating the Wallet Instance
+const integrityContext = getIntegrityContext(integrityKeyTag);
+
+// Get env URLs
+const { WALLET_PROVIDER_BASE_URL } = env; // Let's assume env is an object containing the environment variables
+
+// The list of crypto contexts for each key to attest.
+const keysToAttest: KeyAttestationCryptoContext[] = [
+  {
+    ...createCryptoContextFor("example-keytag"),
+    generateKeyWithAttestation(challenge: string) {
+      // Generate a key stored in a trustworthy WSCD.
+      // On Android this function must return a key attestation.
+      return { 
+        success: true,
+        attestation: "android-key-attestation-string",
+      };
+    }
+  }
+];
+
+/**
+ * Obtain a new Wallet Unit Attestation.
+ * WARNING: The integrity context must be the same used when creating the Wallet Instance with the same keytag.
+ */
+const wallet = new IoWallet({ version: "1.3.3" });
+const issuedAttestation = await wallet.WalletUnitAttestation.getAttestation(
+  {
+    walletProviderBaseUrl: WALLET_PROVIDER_BASE_URL,
+    walletSolutionId: "exampleId",
+    walletSolutionVersion: "1.2.3",
+  },
+  {
+    keysToAttest,
+    integrityContext,
+    appFetch,
+  }
+);
+```
+## Mapped results
+
+The following errors are mapped to a `WalletProviderResponseError` with specific codes.
+
+|HTTP Status|Error Code|Description|
+|-----------|----------|-----------|
+|`*`|`ERR_IO_WALLET_PROVIDER_GENERIC_ERROR`|This is a generic error code to map unexpected errors that occurred when interacting with the Wallet Provider.|
+

package/src/wallet-unit-attestation/api/index.ts

@@ -0,0 +1,51 @@
+import type { IntegrityContext } from "../../utils/integrity";
+import type { KeyAttestationCryptoContext } from "../../utils/crypto";
+import type {
+  DecodedWalletUnitAttestation,
+  WalletAttestation,
+  WalletAttestationRequestParams,
+} from "./types";
+
+interface UnsupportedApi {
+  isSupported: false;
+}
+
+export type WalletUnitAttestationApi =
+  | WalletUnitAttestationSupportedApi
+  | UnsupportedApi;
+
+export interface WalletUnitAttestationSupportedApi {
+  isSupported: true;
+
+  /**
+   * Request a Wallet Unit Attestation (WUA) to the Wallet provider with one or more keys to attest.
+   * Each key must be provided as a {@link KeyAttestationCryptoContext}.
+   *
+   * @param requestParams Wallet Provider data for the Wallet Attestation request
+   * @param ctx.keysToAttest The list of KeyAttestationCryptoContext's of the keys to attest
+   * @param ctx.integrityContext The hardware key pair associated with the Wallet Instance
+   * @param ctx.appFetch (optional) Http client
+   * @returns The generated Wallet Unit Attestation with the attested keys
+   */
+  getAttestation(
+    requestParams: WalletAttestationRequestParams,
+    ctx: {
+      keysToAttest: KeyAttestationCryptoContext[];
+      integrityContext: IntegrityContext;
+      appFetch?: GlobalFetch["fetch"];
+    }
+  ): Promise<WalletAttestation>;
+
+  /**
+   * Decode a given JWT to get the parsed Wallet Unit Attestation object they define.
+   * It ensures provided data is in a valid shape.
+   *
+   * It DOES NOT verify token signature.
+   *
+   * @param token The encoded token that represents a valid jwt for Wallet Unit Attestation
+   * @returns The validated Wallet Unit Attestation object
+   * @throws A decoding error if the token doesn't resolve in a valid JWT
+   * @throws A validation error if the provided data doesn't result in a valid Wallet Unit Attestation
+   */
+  decode(token: string): DecodedWalletUnitAttestation;
+}

package/src/wallet-unit-attestation/api/types.ts

@@ -0,0 +1,49 @@
+import * as z from "zod";
+import { UnixTime } from "../../utils/zod";
+import { JWK } from "../../utils/jwk";
+
+const Status = z.object({
+  status_list: z.object({
+    idx: z.number(),
+    uri: z.string(),
+  }),
+});
+
+/**
+ * Common Wallet Unit Attestation shape. This object is
+ * an abstraction over the version-specific JWTs.
+ */
+export type DecodedWalletUnitAttestation = z.infer<
+  typeof DecodedWalletUnitAttestation
+>;
+export const DecodedWalletUnitAttestation = z.object({
+  attested_keys: z.array(JWK),
+  user_authentication: z.array(z.string()),
+  key_storage: z.array(z.string()),
+  status: Status,
+  eudi_wallet_info: z.object({
+    general_info: z.object({
+      wallet_provider_name: z.string(),
+      wallet_solution_id: z.string(),
+      wallet_solution_version: z.string(),
+    }),
+    key_storage_info: z.object({
+      keys_exportable: z.boolean(),
+      storage_type: z.string(),
+    }),
+  }),
+  iss: z.string(),
+  iat: UnixTime,
+  exp: UnixTime,
+});
+
+export type WalletAttestation = {
+  format: string;
+  attestation: string;
+};
+
+export type WalletAttestationRequestParams = {
+  walletProviderBaseUrl: string;
+  walletSolutionId: string;
+  walletSolutionVersion: string;
+};

package/src/wallet-unit-attestation/index.ts

@@ -0,0 +1,3 @@
+export type * from "./api";
+export { WalletUnitAttestation as V1_0_0 } from "./v1.0.0";
+export { WalletUnitAttestation as V1_3_3 } from "./v1.3.3";

package/src/wallet-unit-attestation/v1.0.0/index.ts

@@ -0,0 +1,5 @@
+import type { WalletUnitAttestationApi } from "../api";
+
+export const WalletUnitAttestation: WalletUnitAttestationApi = {
+  isSupported: false,
+};

package/src/wallet-unit-attestation/v1.3.3/index.ts

@@ -0,0 +1,11 @@
+import { withMapper } from "../../utils/mappers";
+import type { WalletUnitAttestationApi } from "../api";
+import { decode } from "./utils";
+import { mapToDecodedWalletUnitAttestation } from "./mappers";
+import { getAttestation } from "./issuing";
+
+export const WalletUnitAttestation: WalletUnitAttestationApi = {
+  isSupported: true,
+  getAttestation,
+  decode: withMapper(mapToDecodedWalletUnitAttestation, decode),
+};

package/src/wallet-unit-attestation/v1.3.3/issuing.ts

@@ -0,0 +1,147 @@
+import { Platform } from "react-native";
+import { SignJWT, thumbprint } from "@pagopa/io-react-native-jwt";
+import { Logger, LogLevel } from "../../utils/logging";
+import { getWalletProviderClient } from "../../client";
+import { fixBase64EncodingOnKey, JWK } from "../../utils/jwk";
+import { IoWalletError } from "../../utils/errors";
+import type { KeyAttestationCryptoContext } from "../../utils/crypto";
+import type { WalletUnitAttestationSupportedApi } from "../api";
+import { WalletUnitAttestationResponse } from "./types";
+
+/**
+ * Create a Key Attestation Request in JWT format for the provided key.
+ * @param challenge The challenge for key attestation
+ * @param cryptoContext The crypto context of the key to attest
+ * @returns The key attestation request JWT, the public key and the original crypto context
+ */
+const createKeyAttestationRequest = async (
+  challenge: string,
+  cryptoContext: KeyAttestationCryptoContext
+) => {
+  const { success, attestation } =
+    await cryptoContext.generateKeyWithAttestation(challenge);
+
+  if (!success) {
+    throw new IoWalletError(
+      "generateKeyWithAttestation failed to generate a cryptographic key for the Wallet Unit Attestation request"
+    );
+  }
+
+  if (Platform.OS === "android" && !attestation) {
+    throw new IoWalletError(
+      "Missing key attestation: on Android the generated key must have a key attestation to request a Wallet Unit Attestation"
+    );
+  }
+
+  const publicKey = JWK.parse(await cryptoContext.getPublicKey());
+
+  const requestJwt = await new SignJWT(cryptoContext)
+    .setPayload({
+      wscd_key_attestation: {
+        storage_type: "LOCAL_NATIVE",
+        ...(attestation && { attestation }),
+      },
+      cnf: {
+        jwk: fixBase64EncodingOnKey(publicKey),
+      },
+    })
+    .setProtectedHeader({
+      kid: publicKey.kid,
+      typ: "key-attestation-request+jwt",
+    })
+    .setIssuedAt()
+    .setExpirationTime("1h")
+    .sign();
+
+  return { cryptoContext, publicKey, keyAttestationRequestJwt: requestJwt };
+};
+
+export const getAttestation: WalletUnitAttestationSupportedApi["getAttestation"] =
+  async (
+    { walletProviderBaseUrl, walletSolutionId, walletSolutionVersion },
+    { keysToAttest: keysToAttestContexts, integrityContext, appFetch = fetch }
+  ) => {
+    if (keysToAttestContexts.length === 0) {
+      throw new IoWalletError("At least one key to attest must be provided");
+    }
+
+    const api = getWalletProviderClient({ walletProviderBaseUrl, appFetch });
+
+    const { nonce } = await api.get("/nonce");
+    Logger.log(
+      LogLevel.DEBUG,
+      `Challenge obtained from ${walletProviderBaseUrl}: ${nonce}`
+    );
+
+    const keysToAttest = await Promise.all(
+      keysToAttestContexts.map((cryptoContext) =>
+        createKeyAttestationRequest(nonce, cryptoContext)
+      )
+    );
+
+    // Use the first key to attest to sign the WUA Request JWT
+    const signatureKey = keysToAttest.at(0)!;
+
+    const hardwareKeyTag = integrityContext.getHardwareKeyTag();
+
+    const clientData = {
+      challenge: nonce,
+      jwk_thumbprints: await Promise.all(
+        keysToAttest.map((k) => thumbprint(k.publicKey))
+      ),
+    };
+
+    const { signature, authenticatorData } =
+      await integrityContext.getHardwareSignatureWithAuthData(
+        JSON.stringify(clientData)
+      );
+
+    const signedAttestationRequest = await new SignJWT(
+      signatureKey.cryptoContext
+    )
+      .setPayload({
+        nonce,
+        hardware_key_tag: hardwareKeyTag,
+        iss: hardwareKeyTag,
+        keys_to_attest: keysToAttest.map((k) => k.keyAttestationRequestJwt),
+        hardware_signature: signature,
+        integrity_assertion: authenticatorData,
+        platform: Platform.OS,
+        wallet_solution_id: walletSolutionId,
+        wallet_solution_version: walletSolutionVersion,
+        cnf: {
+          jwk: fixBase64EncodingOnKey(signatureKey.publicKey),
+        },
+      })
+      .setProtectedHeader({
+        kid: signatureKey.publicKey.kid,
+        typ: "wua-request+jwt",
+      })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign();
+
+    Logger.log(
+      LogLevel.DEBUG,
+      `Signed attestation request: ${signedAttestationRequest}`
+    );
+
+    const response = await api
+      .post("/wallet-unit-attestations", {
+        header: {
+          "Content-Type": "text/plain",
+        },
+        body: signedAttestationRequest,
+      })
+      .then(WalletUnitAttestationResponse.parse);
+
+    Logger.log(
+      LogLevel.DEBUG,
+      `Obtained Wallet Unit Attestation: ${response.wallet_unit_attestation}`
+    );
+
+    return {
+      format: "jwt",
+      attestation: response.wallet_unit_attestation,
+    };
+  };

package/src/wallet-unit-attestation/v1.3.3/mappers.ts

@@ -0,0 +1,10 @@
+import { createMapper } from "../../utils/mappers";
+import { DecodedWalletUnitAttestation } from "../api/types";
+import { WalletUnitAttestationJwt } from "./types";
+
+export const mapToDecodedWalletUnitAttestation = createMapper<
+  WalletUnitAttestationJwt,
+  DecodedWalletUnitAttestation
+>((x) => x.payload, {
+  outputSchema: DecodedWalletUnitAttestation,
+});

package/src/wallet-unit-attestation/v1.3.3/types.ts

@@ -0,0 +1,21 @@
+import * as z from "zod";
+import { Jwt } from "../../wallet-instance-attestation/common/types";
+import { DecodedWalletUnitAttestation } from "../api/types";
+
+export type WalletUnitAttestationJwt = z.infer<typeof WalletUnitAttestationJwt>;
+export const WalletUnitAttestationJwt = z.object({
+  header: z.intersection(
+    Jwt.shape.header,
+    z.object({
+      typ: z.literal("key-attestation+jwt"),
+    })
+  ),
+  payload: DecodedWalletUnitAttestation, // The payload type matches the public API
+});
+
+export type WalletUnitAttestationResponse = z.infer<
+  typeof WalletUnitAttestationResponse
+>;
+export const WalletUnitAttestationResponse = z.object({
+  wallet_unit_attestation: z.string(),
+});

package/src/wallet-unit-attestation/v1.3.3/utils.ts

@@ -0,0 +1,14 @@
+import { decode as decodeJwt } from "@pagopa/io-react-native-jwt";
+import { WalletUnitAttestationJwt } from "./types";
+
+/**
+ * Decode a given JWT to get the parsed Wallet Unit Attestation object they define.
+ * It ensures the provided data is in a valid shape, but it DOES NOT verify the signature.
+ */
+export function decode(token: string): WalletUnitAttestationJwt {
+  const decodedJwt = decodeJwt(token);
+  return WalletUnitAttestationJwt.parse({
+    header: decodedJwt.protectedHeader,
+    payload: decodedJwt.payload,
+  });
+}