@pagopa/io-react-native-wallet 0.17.0 → 0.17.1

package/lib/module/credential/issuance/README.md

@@ -0,0 +1,323 @@
+# Credential Issuance
+
+This flow is used to obtain a credential from a credential issuer. Each step in the flow is imported from the related file which is named with a sequential number.
+
+There's a fork in the flow which is based on the type of the credential that is being requested. If the credential is an eID, the flow takes a different path than if it is not an eID.
+This is due to the fact that eID credentials require a different authorization flow than other credentials, which is accomplished by a strong authentication method like SPID or CIE.
+Credentials instead require a simpler authorization flow and they require other credentials to be presented in order to be issued.
+
+The supported credentials are defined in the entity configuration of the issuer which is evaluted and parsed in the `evaluateIssuerTrust` step.
+
+## Sequence Diagram
+
+```mermaid
+graph TD;
+    0[WalletInstanceAttestation.getAttestation]
+    1[startFlow]
+    2[evaluateIssuerTrust]
+    3[startUserAuthorization]
+    C4[getRequestedCredentialToBePresented]
+    C4.1[completeUserAuthorizationWithFormPostJwtMode]
+    E4[completeUserAuthorizationWithQueryMode]
+    5[authorizeAccess]
+    6[obtainCredential]
+    7[verifyAndParseCredential]
+    credSel{Is credential an eID?}
+
+    0 --> 1
+    1 --> 2
+    2 --> 3
+    3 --> credSel
+    credSel -->|Yes| E4
+    credSel -->|No| C4
+    C4 --> C4.1
+    C4.1 --> 5
+    E4 --> 5
+    5 --> 6
+    6 --> 7
+```
+
+## Mapped results
+
+### 404 Not Found (CredentialNotEntitledError)
+
+A `404 Not Found` response is returned by the credential issuer when the authenticated user is not entitled to receive the requested credential.
+
+## Strong authentication for eID issuance (Query Mode)
+
+The eID issuance requires a strong authentication method. Currently SPID (L2), CieID (L2) and CIE+PIN (L3) are supported. The strong authentication method is determined by the IDP hint which is passed to the `completeUserAuthorizationWithQueryMode` function.
+
+For SPID in production the IDP hint can be found [here](https://registry.spid.gov.it/identity-providers), under the `entityId` field. For pre-production environment the IDP hint is `https://demo.spid.gov.it'`.
+
+For CieID(L2) the IDP hint is `https://idserver.servizicie.interno.gov.it/idp/profile/SAML2/POST/SSO"` for production and `https://collaudo.idserver.servizicie.interno.gov.it/idp/profile/SAML2/POST/SSO` for pre-production.
+
+CIE+PIN(L3) requires a different flow due to the physical card presence. Helper functions are exposed to handle it and the documentation can be found [here](../../cie/README.md).
+
+The expected result from the authentication process is in provided in the query string as defined in the [JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/oauth-v2-jarm.html#name-response-mode-queryjwt).
+
+## Authentication through credentials (Form Post JWT Mode)
+
+When the credential is different than an eID, the flow requires the user to present other credentials in order to obtain the requested one. This is done through the `getRequestedCredentialToBePresented` followed by the `completeUserAuthorizationWithFormPostJwtMode`.
+
+The expected result from the authentication process is in `form_post.jwt` format as defined in [JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/oauth-v2-jarm.html#name-response-mode-form_postjwt).
+
+## Examples
+
+<details>
+  <summary>Credential issuance flow</summary>
+
+```ts
+// Retrieve the integrity key tag from the store and create its context
+const integrityKeyTag = "example"; // Let's assume this is the key tag used to create the wallet instance
+const integrityContext = getIntegrityContext(integrityKeyTag);
+
+// generate Key for Wallet Instance Attestation
+// ensure the key esists befor starting the issuing process
+await regenerateCryptoKey(WIA_KEYTAG); // Let's assume this function regenerates this ephemeral key
+const wiaCryptoContext = createCryptoContextFor(WIA_KEYTAG);
+
+const { WALLET_PROVIDER_BASE_URL, WALLET_EAA_PROVIDER_BASE_URL, REDIRECT_URI } =
+  env; // Let's assume these are the environment variables
+
+/**
+ * Obtains a new Wallet Instance Attestation.
+ * WARNING: The integrity context must be the same used when creating the Wallet Instance with the same keytag.
+ */
+const walletInstanceAttestation =
+  await WalletInstanceAttestation.getAttestation({
+    wiaCryptoContext,
+    integrityContext,
+    walletProviderBaseUrl: WALLET_PROVIDER_BASE_URL,
+    appFetch,
+  });
+
+const credentialType = "someCredential"; // Let's assume this is the credential type
+
+const eid = {
+  credential: "example",
+  parsedCredential: "example"
+  keyTag: "example";
+  credentialType: "eid";
+};
+
+const eidCryptoContext = createCryptoContextFor(eid.keyTag);
+
+// Create credential crypto context
+const credentialKeyTag = uuid.v4().toString();
+await generate(credentialKeyTag); // Let's assume this function generates a new hardware-backed key pair
+const credentialCryptoContext = createCryptoContextFor(credentialKeyTag);
+
+// Start the issuance flow
+const startFlow: Credential.Issuance.StartFlow = () => ({
+  issuerUrl: WALLET_EAA_PROVIDER_BASE_URL,
+  credentialType,
+});
+
+const { issuerUrl } = startFlow();
+
+// Evaluate issuer trust
+const { issuerConf } = await Credential.Issuance.evaluateIssuerTrust(issuerUrl);
+
+// Start user authorization
+const { issuerRequestUri, clientId, codeVerifier, credentialDefinition } =
+  await Credential.Issuance.startUserAuthorization(issuerConf, credentialType, {
+    walletInstanceAttestation,
+    redirectUri,
+    wiaCryptoContext,
+    appFetch,
+  });
+
+const requestObject =
+  await Credential.Issuance.getRequestedCredentialToBePresented(
+    issuerRequestUri,
+    clientId,
+    issuerConf,
+    appFetch
+  );
+
+// The app here should ask the user to confirm the required data contained in the requestObject
+
+// Complete the user authorization via form_post.jwt mode
+const { code } =
+  await Credential.Issuance.completeUserAuthorizationWithFormPostJwtMode(
+    requestObject,
+    { wiaCryptoContext, pidCryptoContext, pid, walletInstanceAttestation }
+  );
+
+// Generate the DPoP context which will be used for the whole issuance flow
+await regenerateCryptoKey(DPOP_KEYTAG); // Let's assume this function regenerates this ephemeral key for the DPoP
+const dPopCryptoContext = createCryptoContextFor(DPOP_KEYTAG);
+
+const { accessToken } = await Credential.Issuance.authorizeAccess(
+  issuerConf,
+  code,
+  clientId,
+  redirectUri,
+  codeVerifier,
+  {
+    walletInstanceAttestation,
+    wiaCryptoContext,
+    dPopCryptoContext,
+    appFetch,
+  }
+);
+
+// Obtain the credential
+const { credential, format } = await Credential.Issuance.obtainCredential(
+  issuerConf,
+  accessToken,
+  clientId,
+  credentialDefinition,
+  {
+    credentialCryptoContext,
+    dPopCryptoContext,
+    appFetch,
+  }
+);
+
+// Parse and verify the credential. The ignoreMissingAttributes flag must be set to false or omitted in production.
+const { parsedCredential } = await Credential.Issuance.verifyAndParseCredential(
+  issuerConf,
+  credential,
+  format,
+  { credentialCryptoContext, ignoreMissingAttributes: true }
+);
+
+return {
+  parsedCredential,
+  credential,
+  keyTag: credentialKeyTag,
+  credentialType,
+};
+```
+
+</details>
+
+<details>
+  <summary>eID issuance flow</summary>
+
+```ts
+// Retrieve the integrity key tag from the store and create its context
+const integrityKeyTag = "example"; // Let's assume this is the key tag used to create the wallet instance
+const integrityContext = getIntegrityContext(integrityKeyTag);
+
+// generate Key for Wallet Instance Attestation
+// ensure the key esists befor starting the issuing process
+await regenerateCryptoKey(WIA_KEYTAG); // Let's assume this function regenerates this ephemeral key
+const wiaCryptoContext = createCryptoContextFor(WIA_KEYTAG);
+
+const { WALLET_PROVIDER_BASE_URL, WALLET_EID_PROVIDER_BASE_URL, REDIRECT_URI } =
+  env; // Let's assume these are the environment variables
+
+/**
+ * Obtains a new Wallet Instance Attestation.
+ * WARNING: The integrity context must be the same used when creating the Wallet Instance with the same keytag.
+ */
+const walletInstanceAttestation =
+  await WalletInstanceAttestation.getAttestation({
+    wiaCryptoContext,
+    integrityContext,
+    walletProviderBaseUrl: WALLET_PROVIDER_BASE_URL,
+    appFetch,
+  });
+
+const idpHit = "https://example.com"; // Let's assume this is the IDP hint
+
+const authorizationContext = idpHint.includes("servizicie")
+  ? undefined
+  : {
+      authorize: openAuthenticationSession, // Let's assume this function opens the browser for the user to authenticate
+    };
+/*
+ * Create credential crypto context for the PID
+ * WARNING: The eID keytag must be persisted and later used when requesting a credential which requires a eID presentation
+ */
+const credentialKeyTag = uuid.v4().toString();
+await generate(credentialKeyTag);
+const credentialCryptoContext = createCryptoContextFor(credentialKeyTag);
+
+// Start the issuance flow
+const startFlow: Credential.Issuance.StartFlow = () => ({
+  issuerUrl: WALLET_EID_PROVIDER_BASE_URL,
+  credentialType: "PersonIdentificationData",
+  appFetch,
+});
+
+const { issuerUrl } = startFlow();
+
+// Evaluate issuer trust
+const { issuerConf } = await Credential.Issuance.evaluateIssuerTrust(
+  issuerUrl,
+  { appFetch }
+);
+
+// Start user authorization
+const { issuerRequestUri, clientId, codeVerifier, credentialDefinition } =
+  await Credential.Issuance.startUserAuthorization(issuerConf, credentialType, {
+    walletInstanceAttestation,
+    redirectUri,
+    wiaCryptoContext,
+    appFetch,
+  });
+
+// Complete the authroization process with query mode with the authorizationContext which opens the browser
+const { code } =
+  await Credential.Issuance.completeUserAuthorizationWithQueryMode(
+    issuerRequestUri,
+    clientId,
+    issuerConf,
+    idpHint,
+    redirectUri,
+    authorizationContext
+  );
+
+// Create DPoP context which will be used for the whole issuance flow
+await regenerateCryptoKey(DPOP_KEYTAG);
+const dPopCryptoContext = createCryptoContextFor(DPOP_KEYTAG);
+
+const { accessToken } = await Credential.Issuance.authorizeAccess(
+  issuerConf,
+  code,
+  clientId,
+  redirectUri,
+  codeVerifier,
+  {
+    walletInstanceAttestation,
+    wiaCryptoContext,
+    dPopCryptoContext,
+    appFetch,
+  }
+);
+
+// Obtain che eID credential
+const { credential, format } = await Credential.Issuance.obtainCredential(
+  issuerConf,
+  accessToken,
+  clientId,
+  credentialDefinition,
+  {
+    credentialCryptoContext,
+    dPopCryptoContext,
+    appFetch,
+  }
+);
+
+// Parse and verify the eID credential
+const { parsedCredential } = await Credential.Issuance.verifyAndParseCredential(
+  issuerConf,
+  credential,
+  format,
+  { credentialCryptoContext }
+);
+
+return {
+  parsedCredential,
+  credential,
+  keyTag: credentialKeyTag,
+  credentialType,
+};
+```
+
+The result of this flow is a row credential and a parsed credential which must be stored securely in the wallet along with its crypto key.
+
+</details>

package/lib/module/credential/presentation/README.md

@@ -0,0 +1,3 @@
+# Credential presentation
+
+Currently this flow is outdated.

package/lib/module/credential/status/README.md

@@ -0,0 +1,64 @@
+# Credential Status Attestation
+
+This flow is used to obtain a credential status attestation from its credential issuer. Each step in the flow is imported from the related file which is named with a sequential number.
+The credential status attestation is a JWT which contains the credential status which indicates if the credential is valid or not.
+The status attestation is supposed to be stored securely along with the credential. It has a limited lifetime and should be refreshed periodically according to the `exp` field in the JWT payload.
+
+## Sequence Diagram
+
+```mermaid
+graph TD;
+    0[startFlow]
+    1[statusAttestation]
+    2[verifyAndParseStatusAttestation]
+
+    0 --> 1
+    1 --> 2
+```
+
+## Mapped results
+
+### 404 Not Found (StatusAttestationInvalid)
+
+A `404 Not Found` response is returned by the credential issuer when the status attestation is invalid.
+
+## Example
+
+<details>
+  <summary>Credential status attestation flow</summary>
+
+```ts
+// Start the issuance flow
+const credentialIssuerUrl = "https://issuer.example.com";
+const startFlow: Credential.Status.StartFlow = () => ({
+  issuerUrl: credentialIssuerUrl, // Let's assum
+});
+
+const { issuerUrl } = startFlow();
+
+// Evaluate issuer trust
+const { issuerConf } = await Credential.Status.evaluateIssuerTrust(issuerUrl);
+
+// Get the credential attestation
+const res = await Credential.Status.statusAttestation(
+  issuerConf,
+  credential,
+  credentialCryptoContext
+);
+
+// Verify and parse the status attestation
+const { parsedStatusAttestation } =
+  await Credential.Status.verifyAndParseStatusAttestation(
+    issuerConf,
+    res.statusAttestation,
+    { credentialCryptoContext }
+  );
+
+return {
+  statusAttestation: res.statusAttestation,
+  parsedStatusAttestation,
+  credentialType,
+};
+```
+
+</details>

package/lib/module/wallet-instance/README.md

@@ -0,0 +1,29 @@
+# Wallet Instance
+
+This flow which consists of a single step, is used to create a wallet instance. The wallet provider must implement its endpoints based on the OpenAPI specification provided in the [wallet-instance.yaml](../../openapi/wallet-provider.yaml) file.
+A service that is responsible for ensuring the integrity of the device where the app is running is required and it's supposed to use [Google Play Integrity API](https://developer.android.com/google/play/integrity/overview) and [Key Attestation](https://developer.android.com/privacy-and-security/security-key-attestation) on Android, [DCAppAttestService](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity) on iOS.
+The suggested way to implement this service is to use [io-react-native-integrity](https://github.com/pagopa/io-react-native-integrity) by providing an [IntegrityContext](../utils/integrity.ts) object.
+An example is provided as follows:
+
+```ts
+// Get env
+const { GOOGLE_CLOUD_PROJECT_NUMBER, WALLET_PROVIDER_BASE_URL } = env; // Let's assume env is an object containing the environment variables
+
+const googleCloudProjectNumber = isAndroid
+  ? GOOGLE_CLOUD_PROJECT_NUMBER
+  : undefined;
+
+await ensureIntegrityServiceIsReady(googleCloudProjectNumber); // Required by io-react-native-integrity to ensure the service is ready
+const integrityKeyTag = await generateIntegrityHardwareKeyTag();
+const integrityContext = getIntegrityContext(integrityKeyTag); // This function is supposed to return an object as required by IntegrityContext.
+
+await WalletInstance.createWalletInstance({
+  integrityContext,
+  walletProviderBaseUrl: WALLET_PROVIDER_BASE_URL,
+  appFetch,
+});
+
+return integrityKeyTag;
+```
+
+The returned `integrityKeyTag` is supposed to be stored and used to verify the integrity of the device in the future when using an `IntegrityContext` object. It must be regenerated if another wallet instance is created.

package/lib/module/wallet-instance-attestation/README.md

@@ -0,0 +1,35 @@
+# Wallet Instance Attestation
+
+This flow consists of a single step and is used to obtain a Wallet Instance Attestation. The wallet provider must implement its endpoints based on the OpenAPI specification provided in the [wallet-instance.yaml](../../openapi/wallet-provider.yaml) file.
+In order to require a status attestation the consumer application must provide:
+
+- `wiaCryptoContext` object that is used to sign the attestation request. The key must be generated before creating the crypto context;
+- `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;
+
+```ts
+// 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);
+
+// generate Key for Wallet Instance Attestation
+// ensure the key esists befor starting the issuing process
+await regenerateCryptoKey(WIA_KEYTAG); // Let's assume WI_KEYTAG is a constant string and regenerateCryptoKey is a function that regenerates the key each time it is called
+const wiaCryptoContext = createCryptoContextFor(WIA_KEYTAG);
+
+// Get env URLs
+const { WALLET_PROVIDER_BASE_URL } = env; // Let's assume env is an object containing the environment variables
+
+/**
+ * Obtains a new Wallet Instance Attestation.
+ * WARNING: The integrity context must be the same used when creating the Wallet Instance with the same keytag.
+ */
+const issuedAttestation = await WalletInstanceAttestation.getAttestation({
+  wiaCryptoContext,
+  integrityContext,
+  walletProviderBaseUrl: WALLET_PROVIDER_BASE_URL,
+  appFetch,
+});
+return issuedAttestation;
+```
+
+The returned `issuedAttestation` is supposed to be stored and used for any future operation that requires a Wallet Instance Attestation. The wallet attestation has a limited validity and must be regenerated when it expires.

package/lib/typescript/cie/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/cie/component.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoB,MAAM,OAAO,CAAC;AAYzC,OAAO,EAAE,QAAQ,EAAgB,MAAM,SAAS,CAAC;AA0BjD,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;AAC9C,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC;AAC5C,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC;AAC/C,oBAAY,QAAQ;IAClB,SAAS,YAAY;IACrB,WAAW,cAAc;IACzB,cAAc,iBAAiB;CAChC;AAED,KAAK,SAAS,GAAG;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,UAAU,CAAC;CACrB,CAAC;AAeF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB,WAAY,SAAS,sBAyHjD,CAAC"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/cie/component.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoB,MAAM,OAAO,CAAC;AAYzC,OAAO,EAAE,QAAQ,EAAgB,MAAM,SAAS,CAAC;AA4BjD,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;AAC9C,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC;AAC5C,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC;AAC/C,oBAAY,QAAQ;IAClB,SAAS,YAAY;IACrB,WAAW,cAAc;IACzB,cAAc,iBAAiB;CAChC;AAED,KAAK,SAAS,GAAG;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,UAAU,CAAC;CACrB,CAAC;AAeF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB,WAAY,SAAS,sBAyHjD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagopa/io-react-native-wallet",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Provide data structures, helpers and API for IO Wallet",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",

package/src/cie/README.md

@@ -0,0 +1,6 @@
+# CIE
+
+This library provides a components and a set of utilities to interact with the physical [CIE (Carta d'Identità Elettronica)](https://www.cartaidentita.interno.gov.it/) card. It can be used to [obtain an eID](../credential/issuance/README.md) via strong authentication.
+Under the hood it uses [@pagopa/react-native-cie](https://github.com/pagopa/io-cie-sdk) to interact with the card and [react-native-webview](https://github.com/react-native-webview/react-native-webview) to complete the authorization flow.
+
+An example of usage can be found in the [example](./example) folder of this repository.

package/src/cie/component.tsx

@@ -12,6 +12,8 @@ import type {
 import { startCieAndroid, startCieiOS, type ContinueWithUrl } from "./manager";
 import { CieError, CieErrorType } from "./error";
 
+const AUTH_LINK_PATTERN = "lettura carta";
+
 /* To obtain the authentication URL on CIE L3 it is necessary to take the
  * link contained in the "Entra con lettura carta CIE" button.
  * This link can then be used on CieManager.
@@ -21,7 +23,7 @@ const injectedJavaScript = `
     (function() {
       function sendDocumentContent() {
         const idpAuthUrl = [...document.querySelectorAll("a")]
-        .filter(a => a.textContent.includes("lettura carta CIE"))
+        .filter(a => a.textContent.toLowerCase().includes("${AUTH_LINK_PATTERN}"))
         .map(a=>a.href)[0];
 
         if(idpAuthUrl) {