Verafide SDK

Overview

The Verafide SDK allows you to interact with a Verafide system. This SDK is written for use in JavaScript applications.

Quick Start

Installation

Installation is as simple as running an NPM install.

npm install @verafide/sdk

Usage

Two top-level exports are used to create a client object.

The connect function - This function accepts an environment enum, and returns a client object.
The Environment enum - This is a list of the available environments (more about environments).

The example below shows the connect method being called with an environment, and a client object being returned. The client object contains all the methods that allow us to interact with Verafide.

const { connect } = require("@verafide/sdk");

const client = connect();

Environments

The SDK has a library of environments that it can connect to. The enviroment we connect to is chosen by the Enum we pass to connect.

Enum	Enviroment	Description
Environment.TEST	Test	Connects to the test environment.
Environment.UAT	UAT	Connects to the UAT system.
Environment.PRODUCTION	Production	Connects to the public Verafide system.

const { connect, Environment } = require("@verafide/sdk");

const client = connect(Enironment.UAT);

Methods

So, now we have connected to an environment, we can start interacting with it.

Methods

login - Creates a session.
ownedVCs - Requests all of your Verifiable Credentials.
verify - Verify your credentials.
newPresentation - Create a new presentation.
pollPresentation - Check a presentation for updates.
signPresentation - Sign a VC so it's ready to be added to a presentation.
updatePresentation - Update a presentation state.
getCredentialSchemes - Fetch public credential schemas.
getPublicDIDs - Fetch public DIDs.
saveRequestToSign - Create a request for a VC.

VerafideClient.login

Login authenticates our account, and allows us to create a session that grants us use of other methods on the client. This is all handled by the SDK, so we just need to call login once and other methods will begin to work.

Example Use

const myDetails = client.login(
  "my-email@example.com",
  "my-password",
);

Example Response

{
    token: 'fkfa3YAn...',
    userType: 'enduser',
    me: {
        Status: null,
        Message: null,
        userID: 18,
        displayName: 'my-email@example.com',
        firstName: null,
        lastName: null,
        mobilePhone: null,
        addressPrefix: null,
        address1: null,
        address2: null,
        address3: null,
        address4: null,
        postalCode: null,
        country: null,
        memorableQuestion: null,
        memorableAnswer: null,
        profileText: '',
        defaultHomePage: null,
        companyName: null,
        phoneCode: null,
        phoneNumber: null,
        language: null,
        reference: null,
        emailAddress: 'my-email@example.com',
        profilePicture: '',
        apiKey: '4UWARFBT...'
    },
    permissions: {
        permissionAreas: [
            {
                Status: 'OK',
                Message: '',
                name: 'siteAccessUser',
                type: 'tx',
                read: false,
                insert: false,
                update: false,
                delete: false,
                delegate: false
            },
        ],
        permissionGroups: [
            {
                Status: 'OK',
                Message: 'Success',
                groupid: 18,
                groupname: 'JSON Users',
                groupistx: 1,
                chainid: 0,
                candelegate: 1
            }
        ]
    }
}

VerafideClient.ownedVCs

This method requests all your signed Verifiable Credentials (VCs). VCs that are signed, are live credentials that you can present until their expiry. VCs that you have requested will not be returned by this request.

Example Use

const myVCs = await client.ownedVCs();

Example Response

[
    {
        vcid: 1,
        logourl: null,
        type: 'Credential Name',
        category: null,
        requestedby: 8,
        vc: {
            '@context': 'https://www.w3.org/2018/credentials/v1',
            credentialStatus: { ... },
            credentialSubject: { ... }, // Credential content.
            expirationDate: '2022-04-27T15:29:48.989410Z',
            id: 'uuid:ffeedb5e-8a67-4730...',
            issuanceDate: '2021-04-27T15:29:48.989410Z',
            issuer: 'did:setl:DxJKhK...',
            proof: [ ... ],
            type: ['Credential Name']
        },
        state: 1,
        vcId: 1,
        credentialName: 'Credential Name',
        issuer: 'Issuer Name'
    }
]

VerafideClient.verify

The verify method allows you to check that a VC is valid. This is a cryptographic verification that happens on the SETL Blockchain.

Example Usage

const verified = await client.verify({
    '@context': 'https://www.w3.org/2018/credentials/v1',
    credentialStatus: { ... },
    credentialSubject: { ... },
    expirationDate: '2022-04-27T15:29:48.989410Z',
    id: 'uuid:ffeedb5e-8a67-4730...',
    issuanceDate: '2021-04-27T15:29:48.989410Z',
    issuer: 'did:setl:DxJKhK...',
    proof: [ ... ],
    type: ['Credential Name']
});

Important: Note that the parameter for the verify method is the vc key of the verified credential, not the top level object.

Example Response

// For a valid credential.
{
    ok: true,
    verifyType: 'CREDENTIAL'
}

// For an expired credential.
{
    detail: 'Credential uuid:7c5c2275... NOT verified as it expired at 2021-04-29T00:00:00Z and it is now 2021-05-20T14:08:13.833456Z',
    ok: false,
    verifyType: 'CREDENTIAL'
},

// For a tampered credential.
{
    detail: 'Credential uuid:ffeedb5e... has a bad signature: Incorrect signature',
    ok: false,
    verifyType: 'CREDENTIAL'
}

VerafideClient.newPresentation

This method allows you to create a presentation. A presentation has a secret token is generated that allows a vendor to request your presentation. Once shared with a vendor, they will process the token and add their details to the presentation. Once their details are saved onto the presentation, we can sign a VC for the presentation and save it too. The Vendor will then be able to view your credential and verify that you hold it.

Example Use

const presentation = await client.newPresentation('Credential Name');

Example Response

{
    token: 'wvmwHa...',
    type: 'Credential Name',
    vcblob: '',
    state: 0,
    vcwalletid: null,
    vclabel: null,
    orgwalletid: null,
    orglabel: null
}

Please refer to the Presentation States section below for details about presentation state.

VerafideClient.pollPresentation

This method requests the state of a presentation. This is usually done to see if a Verafide vendor or person has processed your secret token generated by newPresentation and saved their details into the presentation.

Example Use

const presentationState = await client.pollPresentation('wvmwHa...');

Example Response

// This is the same response you get from newPresentation, but with updates.
{
    token: 'wvmwHa...',
    type: 'Credential Name',
    vcblob: '',
    state: 0,
    vcwalletid: null,
    vclabel: null,
    orgwalletid: null,
    orglabel: null
}

Note: Both keys orgwalletid and orglabel will be updated with value when a vendor or user has processes your new presentation token.

Please refer to the Presentation States section below for details about presentation state.

VerafideClient.signPresentation

This method produces a signed VC, ready to be added to a presentation. The output from this method can be used directly to update a presentation using updatePresentation.

Example Use

const signedVC = await client.signPresentation({
    '@context': 'https://www.w3.org/2018/credentials/v1',
    credentialStatus: { ... },
    credentialSubject: { ... },
    expirationDate: '2022-04-27T15:29:48.989410Z',
    id: 'uuid:ffeedb5e-8a67-4730...',
    issuanceDate: '2021-04-27T15:29:48.989410Z',
    issuer: 'did:setl:DxJKhK...',
    proof: [ ... ],
    type: ['Credential Name']
});

Important: Note that the parameter for the signPresentation method is the vc key of the verified credential, not the top level object.

Example Response

{
    '@context': [ 'https://www.w3.org/2018/credentials/v1' ],
    proof: {
        created: '2021-05-20T15:45:27Z',
        jws: 'eyJhbGciO...',
        salt: ';_*o9Lm$...',
        type: 'CanonicalJsonWithJws',
        verificationMethod: 'did:setl:3Yix10...'
    },
    type: [ 'VerifiablePresentation' ],
    verifiableCredential: [
        {
            '@context': 'https://www.w3.org/2018/credentials/v1',
            credentialStatus: [Object],
            credentialSubject: [Object],
            expirationDate: '2022-05-13T10:38:01.178296Z',
            id: 'uuid:ea936354-d258-40ad...',
            issuanceDate: '2021-05-13T10:38:01.178296Z',
            issuer: 'did:setl:DxJKhKo...',
            proof: [Object],
            type: [Array]
        }
    ]
}

VerafideClient.updatePresentation

This method is a vital part of the presentation process. It allows you to update a presentation to show that you have either cancelled it, or that you have accepted their details and are presenting your VC; by adding a signed VC to the presentation and updating the state as shown below.

Example Use

// A vendor updating that they have scanned.
// This populates the vendor's walletID, allowing the presenter to see the vendor's name.
const updatedPresentation = await client.updatePresentation(
    'wvmwHa...' // The presentation token.
    null, // This should be the response from `signCredential`.
    1, // State 1 means "Scanned" (refer to Presentation States section below).
    null, // The VC holder's walletID (user presenting).
    2 // The Org Wallet ID (vendor).
);

// A user adding their signed credential, and setting the VC Added state.
const updatedPresentation = await client.updatePresentation(
    'wvmwHa...' // The presentation token.
    signedVC, // This should be the response from `signCredential`.
    2, // State 2 means "VC Added" (refer to Presentation States section below).
    3, // The VC holder's walletID (user presenting).
    null // The Org Wallet ID (vendor).
);

Example Response

// Once updated with vendor walletID and to state 1 (Scanned).
{
  token: 'wvmwHa...',
  type: 'Credential Name',
  vcblob: '',
  state: 1,
  vcwalletid: null,
  vclabel: null,
  orgwalletid: 2,
  orglabel: 'Issuer'
}

// Once updated with VC and to state 2 (VC Added).
{
  token: 'wvmwHa...',
  type: 'Credential Name',
  vcblob: 'eyJAY29...h3sJh==',
  state: 2,
  vcwalletid: 3,
  vclabel: 'my-email@example.com',
  orgwalletid: 2,
  orglabel: 'Issuer'
}

VerafideClient.getCredentialSchemes

This method returns all public credential schemas. A credential schema is a template for a VC contains all the information required to request a VC, such as what fields are required, who can issue the schema as a VC and the logo image hash of that schema.

Example Use

const schemas = await client.allCredentialSchemes();

Example Response

[
    {
        id: 6,
        name: 'Credential Name',
        description: 'This is an example credential.',
        data: {
            fields: [ 'field1', 'field2', ], // Fields required when requesting a VC of this schema.
            issuers: [ 'did:setl:DxJKhK...' ], // Issuers that can sign a request.
            ownerDID: 'did:setl:DxJKhK...' // The creator of this credential.
        },
        state: 1,
        creatorWallet: 2,
        creatorLabel: 'Issuer',
        approverWallet: 1, // The approver is the Verafide admin.
        approverLabel: 'Verafide',
        category: 3,
        categoryLabel: 'ID',
        logoHash: 'c9c7b47...',
        dateCreated: '2021-05-12T11:32:25.566Z',
        comments: '',
        typeDefinition: 'did:setl:cwFBU64...'
    }
]

VerafideClient.getPublicDIDs

Get Public DIDs returns a list of all public DIDs registered on the system. A DID is a unique identifier for each user and is used to identify users within credentials. DIDs are public if the user selects to be registered publicly upon sign-up or if they're a public issuer.

Example Use

const publicDIDs = await client.getPublicDIDs();

Example Response

[
    {
        did: 'did:setl:DxJKhK...',
        walletid: 2,
        label: 'Issuer',
        visible: 1
    }
]

VerafideClient.saveRequestToSign

This method allows a user to request a VC from an issuer or allows an issuer to issue a VC to a user. This request heavily relies on credential information returned from the getCredentialSchemes and getPublicDIDs methods.

Example Use

const vcRequest = await client.saveRequestToSign(
    { field1: 'text', field2: 'more text' }, // These should match the fields of the schema being request, as per `getCredentialSchemes`.
    'Credential Name', // The schema name, as per `getCredentialSchemes`.
    2, // Wallet ID of a DID that is an issuer of this credential.
    "request", // Flag that we're requesting, not issuing.
    6, // The credential ID, as per `getCredentialSchemes`.
    true // Flag to notify the issuer of the request.
);

Example Response

{
  vcId: 1,
  vc: 'eyJ0b1J...',
  state: 0,
  credentialID: 6
}

Reference

Presentation States

These are the list of states a presentation can be in.

State	Description
0	Pending - New created.
1	Scanned - A vendor or user has processed the token (usually transferred by QR Code).
2	VC Added - The VC holder has signed their VC and updated the presentation with their signed VC.
3	Delete - The VC holder has cancelled the presentation.
4	Failed - The presentation has failed.
5	Success - The presentation has been successfully presented.

@verafide/sdk

Verafide SDK

Overview

Quick Start

Installation

Usage

Environments

Methods

VerafideClient.login

Example Use

Example Response

VerafideClient.ownedVCs

Example Use

Example Response

VerafideClient.verify

Example Usage

Example Response

VerafideClient.newPresentation

Example Use

Example Response

VerafideClient.pollPresentation

Example Use

Example Response

VerafideClient.signPresentation

Example Use

Example Response

VerafideClient.updatePresentation

Example Use

Example Response

VerafideClient.getCredentialSchemes

Example Use

Example Response

VerafideClient.getPublicDIDs

Example Use

Example Response

VerafideClient.saveRequestToSign

Example Use

Example Response

Reference

Presentation States

Readme

Keywords

Package Sidebar

Install

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads