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

package/src/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/src/credential/presentation/README.md

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

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

@@ -462,3 +462,21 @@ export class CredentialRequestError extends IoWalletError {
     this.reason = reason;
   }
 }
+
+/**
+ * Error subclass thrown when a credential cannot be issued immediately because it follows the async flow.
+ */
+export class CredentialIssuingNotSynchronousError extends IoWalletError {
+  static get code(): "CREDENTIAL_ISSUING_NOT_SYNCHRONOUS_ERROR" {
+    return "CREDENTIAL_ISSUING_NOT_SYNCHRONOUS_ERROR";
+  }
+
+  code = "CREDENTIAL_ISSUING_NOT_SYNCHRONOUS_ERROR";
+
+  reason: string;
+
+  constructor(message: string, reason: string = "unspecified") {
+    super(serializeAttrs({ message, reason }));
+    this.reason = reason;
+  }
+}

package/src/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/src/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.