Sphereon-OpenSource
SSI SDK
SSI SDK with OID4VC, Presentation Exchange, MS Entra support
This mono repository, contains packages that add support for Presentation Exchange and OpenID4VC (SIOPv2, OID4VCI, OID4VP) and other functionalities to SSI-SDK and Veramo based agents.
We also have additional DID methods and BBS+, RSA key support in our SSI-SDK crypto extensions project, that are compatible with this SSI-SDK and Veramo.
The modules can be integrated in agents running on the issuer, holder and verifier sides, both directly into typescript/javascript projects using NodeJS, mobile projects using React-Native, your browser, or other programming languages using the REST APIs.
OpenID for Verifiable Credentials (OID4VC)
This is a new set of specifications by the OpenID Foundation, that enable peer to peer authentication (SIOPv2), Credential Issuance (OID4VCI) and Credential Presentation/Verification (OID4VP). The SSI-SDK modules offer higher-level and more tight integrations for these specification than our lower level libraries, like OID4VCI, SIOPv2 & OID4VP and Well-known DIDs.
These low-level libraries are typically not too opinionated and require an implementor to do some more work like providing signature/key callback functions. Contrary this SSI-SDK is more opinionated and requires you to use other modules of the SSI-SDK or Veramo to provide certain functionalities, like DID and key management. The benefit however is that it provides a fully working agent solution with a low amount of configuration and/or additional coding in your solution, and a rich ecosystem of plugins.
If you want to test out some of these plugins, we highly recommend using our Open-Source wallet and/or SIOPv2-OID4VP demo deployed at https://ssi.sphereon.com, which are using the plugins below.
| Plugin | Description |
|---|---|
| Presentation Exchange | Allows to persist and manage v1 and v2 Presentation Definitions, as well as Verify Presentation Definitions, create Verifiable Presentations with Submission Data, select and match Credentials and DIDs all stored in the agent. Can be used in both Relying Party/Verifier contexts as holder contexts |
| OID4VCI Issuer storage | Allows to persist and manage OpenID4VCI Metadata and options in the agent database |
| OID4VCI Issuer | OpenID for Verifiable Credentials Issuer core logic and functions. This is the integration of the agent with the low-level OID4VCI client library |
| OID4VCI Issuer REST API | OpenID for Verifiable Credentials Issuer REST API. Exposes both OID4VCI endpoints, as well as status/management endpoints. |
| OID4VCI Issuer REST client | OpenID for Verifiable Credentials Issuer REST client, allowing for easy integration and communication from a webapp with the REST API of the agent. |
| SIOPv2 Authenticator with OID4VP support | OpenID Provider for a wallet/holder context, that allows the agent to authenticate with SIOPv2 against the Relying Party and optionally use OpenID4VP to transport Verifiable Credentials. It is integrated into Key Management system, DID providers and VC modules. Supports JWT and JSON-LD VCs and has support for the JWT VC Presentation Profile |
| SIOPv2 Relying Party logic with OID4VP support | Plugin for a Relying Party agent context, containing the core logic to create Authorization Requests, verify Authorization Responses, as well as handle/manage Presentation Definitions and verifications (OID4VP). It is integrated into the Key Management system, DID providers and VC modules. Supports JWT and JSON-LD VCs and has support for the JWT VC Presentation Profile |
| SIOPv2 Relying Party REST API | Plugin for a Relying Party agent context, it exposes a REST API which allows to integrate into webapps/websites. Support sessions and multiple presentation definitions. You typically run this as a separate agent to your application, but it could be integrated if you want. |
| SIOPv2 Relying Party REST client | Plugin for a Relying Party webapp, it exposes a REST client, allowing for easy integration and communication from the Webapp with the REST API of the Agent. Support creating QR codes for different Presentation Definitions as well as Session Handling. |
Microsoft:registered: Entra Verified ID
The below packages add direct support for Microsoft:registered: Entra Verified ID. These plugins are using Microsoft libraries and REST APIs. Please note that you do not have to use these plugins to be able to support Microsoft:registered: Authenticator, have your agent verify Verifiable Credentials issued by Entra Verified ID, or have your agent communicate with Microsoft Entra Verified ID SIOPv2/OID4VP. The above OID4VC plugins can do these tasks without requiring a direct integration with Microsoft: registered: Entra Verified ID as they conform to the same standards. The biggest exception is issuing VCs using Microsoft:registered: Entra Verified ID. Entra Verified ID will soon have support for OID4VCI, until that time you will have to use their Request API to issue credentials from Entra Verified ID
| Plugin | Description |
|---|---|
| Microsoft:registered: Azure :registered: Authenticator | Plugin to authenticate using the Microsoft:registered: Authentication Library (MSAL) against Microsoft:registered: Azure :registered:. |
| Entra Verified ID Request API | Plugin to use Microsoft:registered: Entra Verified ID's Request API (REST) to issue/verify Verifiable Credentials |
Well-known DIDs
Well-known DIDs allow you to bind domain names to DIDs, by making clever use of Verifiable Credentials signed by the respective DIDs, hosting the result in a well-known location, and then linking to this location from the DIDs itself using service endpoints. We have a low-level library for managing well-known DIDs. The packages in the SSI-SDK provide an integration into DIDs managed by agents using the SDK or Veramo.
| Plugin | Description |
|---|---|
| well-known DID issuer | Supports managing well-known DIDs and configurations. Allows to store them in the agent |
| well-known DID verifier | Verified DIDs and domains to conform to the well-known DID specification |
Contacts and storage
The contact-manager plugin allows you to persist external agent systems like issuers and verifiers. It supports multiple identifiers per contact in the form of correlationIDs, which are URIs as well as assign roles like issuers, holders, verifiers. Typically on a first encounter you would provide a UI to the user asking to provide a name if the protocol cannot already prefill a name. Then the contact gets stored, so simple names can be used instead of DIDs in a UI for instance. It can also be used to manage trust when encountering a certain contact in the future.
| Plugin | Description |
|---|---|
| data-store | TypeORM based contact store to persist and query entities (contacts, identities) |
| contact-manager | Manage contacts and their related identities |
Issuance branding and storage
The issuance-branding plugin allows you to persist branding for issuers and credentials. This allows for these entities to be styled even when there is no active connection possible to the external parties. It supports logo's, background attributes like an image and or color, text color and additional branding information per locale.
| Plugin | Description |
|---|---|
| data-store | TypeORM based issuance branding store to persist and query branding (issuer, credential) |
| issuance-branding | Manage issuer and credential branding |
Generic SSI plugins
Next to the below plugins, we suggest to check out the excelent work done by the Veramo team on the Veramo website. All these SSI-SDK plugins are compatible with Veramo (4.X). Hence you can mix and match the plugins from the SSI-SDK with Veramo plugins. The below plugins add additional functionalities or replace functionalities in Veramo.
| Plugin | Description |
|---|---|
| SSI Types | Generic interfaces for Verifiable Credentials (JWT and JSON-LD) and DIDs. Also supports creating a uniform representation of Credentials, no matter whether they are in JWT or JSON-LD format |
| SSI Core | Adds generic functions used by other plugins, like signing, encoding/decoding |
| DID Utils & Key Utils | Generic key and DID utils can be found in our SSI SDK Crypto Extensions repo |
| JSON LD issuer/verified | Adds JSON-LD issuance and verification for Verifiable Credentials. Integrates seamlessly with Veramo's W3C VC plugin |
| QR code generator | Create generic, SIOPv2/OID4VP, OID4VCI and WACI PEX QR codes. This package specifically targets React and React-Native |
DID resolution
Note: DID resolution is not part of this SDK. We do provide a Universal DID client you can use in Veramo, simply by using the below code when setting up the Agent:
Using the Universal resolver for all DID methods:
export const agent = createAgent<IDIDManager & CredentialIssuerLD & IKeyManager & IDataStore & IDataStoreORM & IResolver>({
plugins: [
// Other plugins
new DIDResolverPlugin({
resolver: new UniResolver({ resolveURL: 'https://dev.uniresolver.io/1.0/identifiers' })
})
]
})Using the Universal resolver for specific DID methods and DID-key:
export const agent = createAgent<IDIDManager & CredentialIssuerLD & IKeyManager & IDataStore & IDataStoreORM & IResolver>({
plugins: [
// Other plugins
new DIDResolverPlugin({
resolver: new Resolver({
...getDidKeyResolver(),
...getUniResolver('lto', { resolveUrl: 'https://uniresolver.test.sphereon.io/1.0/identifiers' }),
...getUniResolver('factom', { resolveUrl: 'https://dev.uniresolver.io/1.0/identifiers' }),
}),
}),
]
})Building and testing
Lerna
The SSI-SDK makes use of Lerna for managing multiple packages. Lerna is a tool that optimizes the workflow around managing multi-package repositories with git and npm / yarn.
Build
The below command builds all packages for you using lerna
yarn buildTest
The test command runs:
jestcoverage
You can also run only a single section of these tests, using for example yarn test:watch.
yarn testUtility scripts
There are other utility scripts that help with development.
yarn prettier- runsprettierto fix code style.
Publish
There are scripts that can publish the following versions:
latestnextunstable
yarn publish:[version]