Negatory. Postpone Mission.

    @verafide/sdk
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.31 • Public • Published

    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

    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.

    Login also returns our user's token, user type, details and permissions for reference.

    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.

    Keywords

    none

    Install

    npm i @verafide/sdk

    Homepage

    verafide.io

    DownloadsWeekly Downloads

    25

    Version

    0.1.31

    License

    Apache-2.0

    Unpacked Size

    1.54 MB

    Total Files

    53

    Last publish

    Collaborators

    • verafide-dev