Unum ID Typescript Server-SDK

This SDK combines the functionality of an Issuer and Verifier entities to work with UnumID's SaaS. For necessary account creation and API keys please email [email protected].

Documentation

Official technical documentation can be found here which is served via our Docusaurus repo. More detailed generated from source documentation can be found here which is served via repo specific Github pages via the /docs folder of the main branch.

Distribution

This project is publicly published on the official npm registry. For example it can be pulled with, npm i @unumid/server-sdk or yarn add @unumid/server-sdk.

Releases

Releases and publishing to NPM is automated via Github Actions CI job. In order to trigger a release one should push a git tag with a preceding v with semver notation, ie v1.1.1, to the main branch. This will trigger the CI job to bump the package version, generate typedocs, publish to NPM, make a release commit, and make a Github Release. The contents of the Github Release are autogenerated based on pull requests with commits associated with the release, so please use PRs to makes changes to main. The message of the git tag will be the commit message for the release so please make it meaningful. For example, git tag v1.1.1 -m "Updated the SDK with a new CI job" && push origin v1.1.1.

Global Dependencies

• NodeJS v14.0.0 or higher, preferably v14.15.0 or higher
• yarn

Environment Variables

The following environment variables are required to be set to use the SDK properly.

• UNUM_ENV
• LOG_LEVEL
• DEBUG

UNUM_ENV

One needs to provide the SDK the with an environment variable to denote its run time environment, i.e. production. For the Typescript SDK this done via the UNUM_ENV environment variable. The three relevant values are: production, sandbox, dev. You need to use one of these exactly in order for the SDK to communicate with Unum ID's SaaS. The default value if nothing is supplied is sandbox.

LOG_LEVEL

The default logs level is info. You can change this to debug for more information (set the environment variable LOG_LEVEL = debug). The logs default to stdout, so you can easily aggregate them from disk using the log provider of your choice.

We use standard NPM log levels. Learn more about these here.

DEBUG

The DEBUG environment variable defaults to false. Setting to true enables logging of decrypted presentations at the debug level. Due to presentations containing potentially sensitive information it is not advised to use in a production environment. Note: the LOG_LEVEL envirnoment variable also needs to be set to at least debug level in order to be visible.

In order to generate the Typedoc documentation from the source code run the createTypedocs.sh script.

Versioning

Information regarding the suggested versioning strategy can be found here. Breaking versions of this SDK will be denoted as such with an incremented major version. However all versions of the SDK will be fully backwards compatible with the other Unum ID SDKs. If there is a need to referencing an older version of the SDK within your applications for other applications specific backwards compatibility we recommend this syntax for simplicity: @unumid/server-sdk-v2": "npm:@unumid/[email protected].

SDK Functionality

The Server SDK uses the UnumDto type to facilitate handling many response body types while providing a reliable structure to access the result body and importantly the rolling JWT authToken.

{
  "authToken": string; // The JWT auth token which is used by the SDK to authenticate with UnumID's SaaS. This is periodically refreshed thus its value should be read and stored in every resultant function call. 
  "body": T; // The placeholder for the function's response type is function specific. 
}

Note: Official documentation can be found here.

Authentication Every request detailed below requires a Bearer authToken as a first parameter which is used to authenticate request to UnumID's SaaS on your behalf. As mention above this auth token updated upon every subsequent function call and should be read via the authToken attribute and persisted accordingly for later requests.

Errors Errors returned by UnumID's SaaS will also be wrapped in the UnumDto object so that the potentially updated authToken can be retrieved. Validation errors which are created prior to any internal calls to UnumID's SaaS will be of type Error and are thrown. This is due to never making a network call with the provided authToken so no potential new authToken to pass back. For this reason we recommend wrapping all SDK calls in a try/catch.

Issuer

The Issuer functionality is used by a customer acting as an Issuer. It allows customers to perform actions such as issuing and revoking Credentials.

registerIssuer

Register an issuer corresponding to your customer UUID and issuer API key provided by UnumID. As a customer, you can register as many issuers as you like (or none at all), depending on your use case. Note, however, that you'll need a unique issuer API key for each one.

You should store the DID (did) and encryption and signing key pairs (keys) that this returns. You'll need these to issue credentials to users.

issueCredentials

Issue a credential to a Subject, also known as a User.

You need to provide your Issuer DID (created when you registered), as well as your signing and encryption private keys, which the Issuer uses to sign and encrypt the credential. You need to specify a credential type, which verifiers will use to later request the credential from the user.

This returns a credential id that should be stored for reference. For example, the credential id is required to revoke the credential if need be. We would recommend storing the entire credential indexed on the resultant credential id. Note that there are also id fields within a credentialSubject and credentialStatus, but these are different. They refer to the subject DID and credential status identifier, respectively, as defined by the W3C spec [1],[2].

Important: The private keys never leave your app. This function, like all the others in this SDK, needs them in order to handle to cryptographic functionality on your behalf.

updateCredentialStatus

Update a credential, i.e. make it invalid.

You need to provide the credential id (created when you issued the credential) and a CredentialStatusOptions status. Currently the only valid status are: verified and revoked.

revokeAllCredentials

Revoke all issued credentials to a particular DID.

You need to provide your issuer's did and signingPrivateKey also the target subjectDid. Only credentials issued by the associated issuer are revoked from the subject. The signing private key is necessary for the request signature to be created within the sdk. The signature is necessary to be verified by the SaaS prior to revoking all the credentials.

verifySubjectCredentialRequests

Verify a Subject's requests for credentials.

You need to provide the your issuer's did along with the SubjectCredentialRequest array from your /userCredentialRequest endpoint.

The array of CredentialRequests are signed by the subject's private key. This function verifies the cryptographic signature is valid. Furthermore, it validates that all requests are from the same subject and that requested Issuer requirements are met. After which, your application code will need to evaluate wether it can issue the requested credentials. An example implementation can be found here.

The main use case of this to allow bootstrapping users that just installed the Unum ID Wallet with credentials necessary to use across the network, i.e for instant sign ups with a partner.

Note: Despite this having "verify" in its name, this function serves Issuers in determining whether a subject's request for credentials is valid. It is up to your application logic to determine whether you have the data relating to the the subject to issue the requested credentials.

verifySignedDid

Verify a signed Decentralized Identifier.

You need to provide the your issuer's did along with the signed DID object.

The DID string is signed by the subject's ECC private key. This function verifies the cryptographic signature is valid.

The main use case is for the /userCredentialRequests required Issuer endpoint. It facilitates getting DID information for users within your service. The User DID is necessary to then issue re-usable identity credentials to.

Verifier

The Verifier functionality is used by a customer acting as a verifier. Most importantly, it allows customers to send PresentationRequests to the UnumID mobile SDK and to verify the encrypted Presentation responses.

registerVerifier

Register a verifier corresponding to your customer UUID and verifier API key that UnumID provides. As a customer, you can register as many verifiers as you like (or none at all), depending on your use case. Note, however, that you'll need a unique verifier API key for each one.

You should store the DID (did) and signing key pair (keys) that this returns. You'll need these to create requests for (presentations of) credentials from users.

sendRequest

Create a request for (a presentation of) credentials from a user.

You need to provide your verifier DID (created when you registered) and the UUID of the holder app from which the user can share the data. You also need to provide your signing private key, which the SDK uses to sign the request.

Important: The signing private key never leaves your app. This function, like all the others in this SDK, is solely using it to handle to cryptographic functionality on your behalf.

To request credentials, you need to populate one or more CredentialRequest objects, defined in the UnumID generic types project and shown below.

verifyPresentation

Handles decrypting the encrypted presentation and verifies the signatures are valid.

You need to be able to receive presentations from users and pass them to this function. To do this, you need to create a /presentation endpoint that conforms to our OpenAPI specification. The Unum ID cloud sends encrypted presentations to this endpoint, which should pass those presentations to the verifyPresentation function to be decrypted and verified.

You need to provide:

1. your verifier did
2. your verifier encryption private key
3. encrypted presentation (received at /presentation endpoint)
4. (optional, but recommended) presentation request (received at /presentation endpoint)

The fist two are returned by registerVerifier.

Important Although the mobile SDK sends the presentations directly to UnumID's SaaS, UnumID never has access to the credentials within the presentation. The mobile SDK encrypts all presentations with the presentation requesting verifier's public key, to which the requestor is the only ones with necessary decryption private key, the Verifier's encryptionPrivateKey, an attribute created with the registerVerifier call.

Note presentationRequest is optional in order for the server sdk can handle verifying presentations that may not have a corresponding request. However, if presentationRequest is supplied from UnumID's SaaS via the /presentation endpoint, it is strongly recommended that it is provided as it performs additional validation checks on your behalf.

sendSms

Use to send a deep link to a user by SMS. A templated message will be delivered from an UnumID associated phone number. You can of course use your own SMS sending service if you prefer.

To request (a presentation of) credentials from a user, you first create the request object and receive a deep link that references it. The user need to receive this deep link, which will open the correct app on their phone and prompt them to share the credentials. SMS is one convenient channel.

The SMS message will be in the format:

• Verification Request: [verifier_name]. Click here to complete: [deep_link]

Note: The verifier is corresponding to the presentation request from which the deeplink references. Because you are the acting verifier, the name will be what ever you provided during verifier registration.

sendEmail

Use to send a deep link to a user by email. A templated message will be delivered from [email protected]. You can of course use your own email sending service if you prefer.

To request (a presentation of) credentials from a user, you first create the request object and receive a deep link that references it. The user need to receive this deep link, which will open the correct app on their phone and prompt them to share the credentials. Email is one convenient channel, though keep in mind that the user will need to click the link from their phone for the deep link to work.

The email will be in the format:

• subject: Verification Request: [verifier_name]
• body: Click here to complete: [deep_link]

Note: The verifier is corresponding to the presentation request from which the deeplink references. Because you are the acting verifier, the name will be what ever you provided during verifier registration.

checkCredentialStatuses

Used to check the status of individual credentials.

The status attribute of the response's CredentialStatusInfo is of type CredentialStatusOptions. Currently the only valid status are: verified and revoked.