Onyx SSI SDK Examples Repository

Introduction

This repository contains a set of comprehensive typescript code examples to demonstrate the capabilities of the Onyx SSI SDK. Each script focuses on a specific function of the SDK.

This repository can also be used as self-help guide for developers who aspire to build their own use-cases using Onyx SSI SDK.

Features

This examples repository covers three important roles in Decentralized Identity:

Issuer

The Issuer plays a crucial role in issuing verifiable credentials (VC) to entities. The scripts demonstrate how to effectively utilize the Onyx SSI SDK to carry out all tasks related to the Issuer. This includes creating a DID (Decentralized Identifier) for the Issuer, generating and signing Verifiable Credentials.

Within the issuer section, you'll find a schema section that defines the structure for the subject data of the verifiable credential. This directory allows you to experiment and create custom schema types tailored to your specific requirements. As part of this examples repository, we have included a pre-defined proofOfName schema.

Holder

The Holder is the entity who claims, shares, and manages their Verifiable Credentials. The examples showcase how the Onyx SSI SDK can be leveraged from the Holder's perspective. Developers will learn how to create a DID, generate Verifiable Presentations (VP) with their desired Credentials, and digitally sign the Presentation for identity verification.

Verifier

The Verifier is an entity seeking to validate claims that a Holder presents. These examples demonstrate how to perform relevant verification. These include JWT verification of the Credential and Presentation and status checks of DIDs within the Credential.

Holistic technology perspective

This repository also demonstrates integrating the SDK into an end-to-end SSI ecosystem, enabling developers to customize digital identity solutions.

With the Onyx SSI SDK and these examples, you'll be equipped to develop robust and interoperable SSI solutions, enhancing digital identity management across diverse applications and industries.

Disclaimer

Note that this repository emphasizes exemplary usage of the Onyx SSI SDK for development purposes. For production-grade use cases, consider additional parameters to ensure the utmost safety and security of your SSI solution. Exercise caution and adopt best practices when deploying SSI solutions in live environments.

Prerequisites

To run the examples in this repository, you need:

• Node.js v16 or higher installed on your system.
• A basic understanding of TypeScript.
• A configured .env file. You'll find a .env.example in the root of this project, which outlines the necessary environment variables.
• Optional but highly encouraged to get familiar with Onyx SSI SDK and the broader SSI Ecosystem.

Getting Started

1. Clone the Repository

   Use the following command to clone this repository to your local machine:

   git clone https://github.com/jpmorganchase/onyx-ssi-sdk-examples
   

2. Navigate to the Directory

   Enter the root directory of the cloned repository with:

   cd onyx-ssi-sdk-examples
   

3. Configure Environment Variables

   Rename the .env.example file to .env and fill it with your own information.

4. Install Dependencies

   Before running any scripts, ensure to install all necessary dependencies:

   npm install
   

Repository Structure

• src/: This directory is the root of the examples repository and contains three subdirectories: holder, issuer, and verifier. Each subdirectory houses TypeScript scripts showcasing specific functionalities of the Onyx SSI SDK, corresponding to the respective roles.
• src/utils/: In this directory, you will find various helper scripts that facilitate the implementation of the examples within this repository. These utility scripts streamline certain processes and enhance the overall development experience.
• src/verifiable_credentials/: This directory serves as the default storage location for all verifiable credentials generated by the issuer scripts. If needed, you can modify the storage location for these credentials by updating the .env file.
• src/verifiable_presentation/: Similar to the verifiable_credentials directory, this folder acts as the default storage location for all verifiable presentations generated by the holder scripts. If necessary, you can adjust the storage location for these presentations in the .env file.

Usage

Navigating the usage of this examples repository is simple and straightforward. Follow these steps to get familiar with the Onyx SSI SDK functionalities:

1. Start from the Issuer section:

   • Here, you will learn how to create and sign a Verifiable Credential. This fundamental step lays the foundation for the rest of the SSI ecosystem.
   • Execute the relevant scripts provided in the issuer subdirectory to experience the issuance process.
   • To issue a Verifiable Credential, the issuer needs to follow a two-step process. First, they must create the VC and then they must sign that VC. You can simply run the "src/issuer/create-and-sign-vc.ts" script, which demonstrates the creation and signing of the VC and generates a "proofOfName" VC. This Verifiable Credential is then stored in the location specified by the "VC_DIR_PATH" environment variable, with the default location being "src/verifiable_credentials".

2. Proceed to Holder section:

   • This part focuses on creating and signing a Verifiable Presentation, enabling the Holder to present their identity credentials securely.
   • Run the appropriate scripts located in the holder subdirectory to grasp the Holder's role in the SSI workflow.
   • To create a Verifiable Presentation, the holder needs to follow a two-step process. First, they must create the VP from an existing VC and then they must sign that VP. You can simply run the "src/holder/create-and-sign-vp.ts" script, which demonstrates the creation and signing of the VP from the VC created in step 1. This Verifiable Presentation is then stored in the location specified by the "VP_DIR_PATH" environment variable, with the default location being "src/verifiable_presentation".

3. Finally, move to the Verifier section:

   • In this part, you will utilize the Verifiable Presentation created in Step 2 to verify the Verifiable Credential generated at Step 1.
   • Execute the applicable scripts found in the verifier subdirectory to understand how verification occurs in the SSI ecosystem.
   • To verify a Verifiable Presentation you can simply run the "src/verifier/verify.ts" script, which demonstrates the verification flow.

To run a specific example, consult the package.json file, which contains instructions on running individual scripts. For instance, to execute a given script, use the following command:

npm run $script

Replace $script with the actual script name specified in the package.json file to launch the corresponding functionality.

How to Contribute

Contributions to this repository are always welcome. Please refer to our CONTRIBUTING.md file for detailed information on how you can contribute.

Issues

If you encounter any issues while using these examples or the SDK, feel free to open an issue in this repository. We'll do our best to address your concerns.

We trust these examples will help you effectively utilize Onyx SSI SDK for your projects. Happy coding!