UI Patterns and Flows

Architecture

The architecture of the Inrupt Data Wallet consists of a Backend-for-Frontend web application pattern with the following key components:

Data Wallet mobile application: The Wallet user-facing mobile application that users interact with. It communicates exclusively with Inrupt’s Enterprise Solid Server (ESS) Wallet Service.

ESS Wallet Service: The Wallet Service acts as an intermediary between the Wallet mobile app and the underlying ESS microservices. The Wallet Service is responsible for:

• Storing data in Pod Services.

• All CRUD operations for the Wallet.

• Provisioning the Wallet storage and the correct authorizations for containers like the inbox.

• Invoking the ESS Access Grants microservice to initiate a consent flow (Access Requests and Access Grants).

• Fetching the WebID from the WebID Service to obtain information about the Wallet user.

The architecture diagram also includes two business data consumer applications that request data from the Wallet Service using Access Requests. The Wallet Service simplifies the management of Access Requests and the generation of Access Grants by communicating with the Access Grants Service and managing the Wallet inbox.

The Wallet Service communicates with the microservices and other components using the Solid protocol.

The Identity Provider plays a key role in the authentication of both user and business data consumers.

At the core of the Wallet security architecture lies a robust set of measures designed to protect the user’s data and ensure the integrity of all interactions. See more at Security.

• Authentication: All Wallet endpoints are authenticated, so only authenticated entities can interact with Wallet Service and the Wallet.

• Authorization and Access Control: Only authorized applications are able to request access to data inside the Wallet. Access Requests and Grants are generated as tamper-proof Verifiable Credentials.

• Encryption: All data transmitted to and from the Wallet is encrypted, ensuring user information remains confidential and protected from interception or unauthorized access during transit.

Wallet Storage Organization

The Wallet uses a simple storage structure to manage resources, receive requests for access to data, and manage the lifecycle of Access Requests and Grants. The following containers are created at provision time.

/wallet
/inbox
/accessgrants
/accessrequests

Manage Access Requests and Grants

The Wallet Service is responsible for managing the state of Access Requests and Grants within the Wallet storage. The Wallet’s role is limited to initiating request actions and invoking the Wallet Service. The Wallet Service is responsible for creating new Access Grants. Most interactions involving the /inbox, /wallet, /accessrequests, and /accessgrants containers are exclusively managed by the Wallet Service.

List Pending Requests

Shows all pending Access Requests the user has not yet accepted or rejected.

It reads the /inbox container, looks for active Access Requests that need to be addressed, and shows them to the user.

Approve Request

The user is able to view an Access Request and approve or reject it. When the Access Request is approved, it moves from the /inbox to the /accessrequests container, and the Access Grant is stored in an /accessgrants container.

List Active Access Grants and Access Requests

The Wallet Service calls the ESS Access Grant Service /derive endpoint and brings back a list of all the active Access Grants. It fetches the revocation list and checks if any of the Access Grants returned have been revoked using the /verify endpoint.

When the user switches to the Request or Access tabs in the Wallet, the Access Grants and Access Requests views on those tabs are synchronized with the ESS Access Grant Service.

View Grant

Viewing an Access Grant displays the following attributes:

• Expiry date

• Purpose

• Resource Name

• Data Requester WebID, and information based on the Data Requester WebID

Revoke Grant

A user can revoke an Access Grant by invoking the /accessgrants/{id} endpoint. Revoking a Grant will impact the /accessgrants container. It removes the active Grant stored in the /accessgrants container and calls the Access Grant service to revoke that Grant.

Download a Resource into the Wallet

This pattern enables users to retrieve a resource from an external application and store it in their Wallet. When resources are available via QR codes, users can scan the QR code representing a resource and store it in their Wallet.

The business data consumer application generates a QR code for a particular resource, such as a verifiable credential. The user then scans the QR code from the Wallet. The Wallet retrieves the resource and sends a request to the Wallet Service to securely store it.

Share a Resource with a Third-Party Application

This pattern preserves the symmetry of an Access Request being made by a requesting party and approved (or rejected) by the user, yet is initiated by the user who initially generates the QR code. This pattern allows the user to interact with a service and share data without that service requiring prior knowledge of the user’s identity.

First, the user selects a resource they wish to share from their Wallet with another party. Then, the Wallet generates a QR code, encompassing all the essential details needed by an external party to create an Access Request and dispatch it back to the user. Subsequently, the data requester creates an Access Request and awaits the user’s approval. Once the user approves the Request, the Access Grant will need to be communicated to the Requester through a webhook or inbox.

The QR code includes a JSON object that contains the WebID and the resource location and holds all the necessary information to generate an Access Request for this resource.

For example:

{
  "webid":"https://www.example.com/id",
  "resource":"https://storage.inrupt.com/934ed7a345/wallet/IMG_0005.jpg"
}

The sequence diagram shows the following:

• The Wallet creates a QR code to share the resource.

• The third-party application scans the QR code, which includes the WebID and Resource URL.

• Using the WebID, the third-party app can dereference the WebID and obtain the inbox URL from the WebID document.

• The third-party application initiates an Access Request using the QR code information.

• The user receives the Access Requests in the Wallet Inbox and accepts the Request.

• The Wallet Service then contacts the ESS Access Grant Service to generate an Access Grant and moves the Access Request from the Inbox to the /accessrequests container. When the Access Grant is received, a copy will be stored in the /accessgrants container.

• The Access Grant is transmitted via webhook or callback to the third-party application, enabling them to execute a read operation on the data.

Sharing Wallet Digital Identity

This scenario discusses how users can share their Wallet’s identity with a third-party application using a QR code. The third-party application can scan a user’s Wallet identity (WebID), which allows the third-party application to generate an Access Request and send it to the Inbox. This capability enables a user to present their WebID for use by other services in the future.

In this pattern, the external application submits a file to be stored in the user’s Wallet. This scenario is akin to scanning a QR code from a generated resource, but for the WebID profile. The profile tab contains a QR code with the embedded WebID. By dereferencing the WebID, the external application will know where to request permission to write data in the Wallet, triggering the consent flow.

The external application scans the profile QR code and issues an Access Request to write in the inbox. After the user accepts the Request, the Grant is stored in an /accessgrants container.

Scan a QR code to share a resource

This pattern enables a user to scan a QR code and subsequently share data with a third party. For instance, this could apply to a car rental website. In this situation, the user scans a QR code, enabling the Wallet to initiate an access prompt. The QR code will encompass the application clientID and data type, which the Wallet activates with the necessary information to send the user an Access Request.

The flow works as follows:

• A user wants to interact with services, yet the services don’t know anything about the user in advance. The service needs enough information about the user to make an Access Request.

• The role of the Access Prompt endpoint is to allow the user’s wallet to interact with it so that it can supply details about itself (about the user) to the service.

• In this implementation, we have encoded the resource type and service cliendID in the QR code that initiates this flow, so that the Wallet UI can determine which resource is going to satisfy the service’s needs. For example, If the initial QR code comes from a car rental company, it might want a driving license credential.

In the sequence diagram, the Wallet scans a QR code that will activate the access prompt endpoint. The data requester app will encounter this prompt with the user information (WebID) and requested details, such as driving license credentials. The data requester app will seek access to this data and send an Access Request to the Inbox, which is configured to have public write access. Once the user accepts, they will receive an active Access Grant in the Access section of the Wallet, enabling the data requester application to read the driver’s license.