npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@identity.com/idv-commons

v2.0.2

Published

Credential Request and Interactive Validation

Downloads

63

Readme

IDV Commons Identity.com Credential Request and Interactive Validation Library

The IDV Common library provides common functionality that will help you when customizing your IDV Builder or IDV Toolkit.

NOTE: We are in the process of Open-Sourcing the IDV Toolkit. Until then, the IDV Builder can be used to join the Identity.com ecosystem.

IDV Commons is provides functionality regarding two main concepts of the IDV Toolkit/Builder:

  • Validation Plans and Handlers
  • Credential Requests

Validation Plans

A validation plan defines the information (in the format of User Collectable Attributes that needs to be successfully validated by the IDV, before the requested credential (Verifiable Credential) can be created and attested to.

The functionality provided IDV Commons for working with Validation Plans can be found in src/vp , the most important one being the abstraction of common Handler use-cases.

Handlers

Handlers are generic abstractions that react to events fired . They have access to the state of the entire validation process, and can therefore be individually as complicated as they need to be. For more information around Handlers and how they fit into the IDV Toolkit architecture please refer to the IDV Builder documentation.

UCA Handler

The IDV Commons library provides an ancestral handler, called UCA Handler(src/vp/Handler.js), that a handler that abstracts a lot of the work around receiving UCA values: By passing the name of a UCA as the constructor parameter, the handleUCA method will be called every time the value of that UCA changes, i.e. when the client has provided the requested information. This method can execute any arbitrary code, for example calling an external API to decide whether to accept or reject the UCA.

To extend/implement a handler logic you should create a new class that extends the `UCA Handler and override the "handler" method.

Example

class MyUCAHandler extends UCAHandler {
   
   constructor(ucaName = null, autoAccept = false, ucaVersion = '1') {
        // it's a good practice to define the ucaName and ucaVersion when exporting the instance
        // but it's ok to not have any constructor params and only initialize the super class with the specific values. 
        super(ucaName, autoAccept, ucaName);
   }

   /**
   * handleUCA is called after all checks are made and base on the value is expected to mutate the usaState
   * value [object] uca value received on the event
   * ucaState [object] the specific uca state in the running process
   **/
   async handleUCA(value, ucaState) {
      // most common changes are setting errors
      // ucaState.errors = [];  

      // and setting new status
      // ucaState.status = UCAStatus.VALIDATING;
   }

  
}

Validating Handler

The IDV Commons library provides an ancestral handler, called Validating Handler that extends UCAHandler and can be used to handle validation process that requires async validations. It automatically sets the associated UCAs status to VALIDATING as long as no exception is thrown.

Example

class MyUCAHandler extends ValidatingHandler {
   
   constructor(ucaName = null, ucaVersion = '1') {
        // it's good practice to define the ucaName and ucaVersion when exporting the instance
        // but it's ok to not have any constructor params and only initialize the super class with the specific values. 
        super(ucaName, ucaName);
   }

   /**
   * Called after all checks are made and base on the value is expected to mutate the usaState
   * @param value [object] uca value received on the event
   * @param ucaState [object] the specific uca state in the running process
   **/
   async handleUCA(value, ucaState) {
      // TODO dispatch the validation process asynchronous adding it to some queue implementation
      super.handleUCA(value, ucaState) 
   }

  
}

Plan Manager

The IDV Commons library provides an abstract class, called PlanManager(src/vp/PlanManager.js), that defines the interface to implement the validation plan resolution. This class includes methods to list the plans supported by an IDV and to retrieve a plan given a credential item type.

The IDV Toolkit supports implementing a custom Plan Manager for an IDV.

Tasks

In many cases, UCA validation may be handled by a service external to the IDV Toolkit, and may take more than a few seconds. In this case, an external task can be added to the process state, that can be resolved later either via a notification or via polling.

For more details please read the IDV Toolkit's ValidationModule documentation on Tasks.

Creating a Task

Here is an example of how to add an external task in handler code, using the createPollingTask defined in src/vp/Tasks.js:

const { Tasks: {  createPollingTask  }} = require('@identity.com/idv-commons');

const handler = (state, event) => {
    // create the task
    const task = createPollingTask({
        taskExpiresAfter: '48h',
        interval: '1h',
        parameters: {
            // details the IDV Toolkit needs to know how to poll
        }
    });

    // trigger the external service, e.g. via an http POST

    // return the updated state
    return {
        ...state,
        externalTasks: [task]
    }
}

External Task Handler

The IDV Commons library provides an ancestral handler, called ExternalTaskHandler that already implements the logic to check if an event is an external task event that should be processed.

Example

class MyUCAHandler extends ExternalTaskHandler {
   
   constructor(eventType, externalTaskName) {
        // it's a good practice to define the eventType and externalTaskName when exporting the instance
        // but it's ok to not have any constructor params and only initialize the super class with the specific values. 
        super(eventType, externalTaskName);
   }

  /**
     * Manipulate the state based on the event and task. Must return the resultant state
     * @param state The incoming state
     * @param event The incoming event
     * @param task The task this event is related to
     * @return {*} The outcoming state
     */
   async handleTask(state, event, task) {
      // TODO process the event and possibly update the state
      return state;
   }
}

Credential Requests

NOTE: Credential Requests do not need to be customized when using the IDV Builder. Thus, this section will be remain a stub and will updated with more details, as soon as the IDV Toolkit is open-sourced.

Under src/cr you will find the CredentialRequest class. It is the model of a user's request (and its lifecycle) to you as an IDV, to attest to a specific credential. Typically this would happen via a mobile client that supports the Identity.com credential creation protocol.