IOTICS Identity Library for JavaScript

Simple wrapper for the IOTICS golang identity library high level API.

Build

The applications are packed with webpack. The libraries are built in the ./dist directory

Install npm dependencies

npm install

Build the library

make build

Test the browser library

make test-browser

Run an http server with make serve and navigate to http://localhost:9090/examples/browser to access the example application at examples/browser

Test node library

make test-node

To run the node example:

node examples/node/example.mjs

TODO

List of things that need to be done

Features

1. Not all APIs have been mapped
2. In nodejs, functions are exported in the global namespace - maybe there's a better way
3. node is using active wait to pause for 1500ms to wait for the functions to be loaded in the js global.

Known Issues

1. Golang wasm compiles net/http client using fetch so, in node node-fetch must be correctly installed and loaded.

How to use it

How to use the library to build your own application.

Load the library

npm i iotics-identity-js

NodeJS

Import the library in NodeJS

import pkg from 'iotics-identity-js/dist/nodejs/ioticsIdentity.js';

See example in examples/nodejs/example.mjs

Browser

If you bundle your browser application, import iotics-identity-js/dist/browser/ioticsIdentity.js, else, copy the files from node_modules/iotics-identity-js/dist/browser in your environment and load them as

  <script src="./ioticsIdentity.js"></script>

Then, in your application:

const { IoticsIdentity, loadLib } = ioticsIdentity;

The loadLib function loads the lib wasm. The IoticsIdentity object is the namespace of the functions of the library.

Objects

Error Error object returned by the functions when an error occurs

{
  "error": "<value>",
  "message": "<value>",
}

GetIdentityOptions Object used to retrieve an identity

{
   "seed": "<string>. base58 encoded>",
   "did": "<string>",
   "key": "<string>",
   "password": "<optional string>",
   "name": "<string, must start with #>"
}

CreateIdentityOptions Object used to create an identity. The override flag is used to override any existing document in the resolver.

{
   "seed": "<string>. base58 encoded>",
   "did": "<string>",
   "key": "<string>",
   "password": "<optional string>",
   "name": "<string, must start with #>",
   "override": "<boolean>"
}

Document The registered DiD document as described here

{
   "@context": "<string>",   
   "id":  "<string>",
   "ioticsSpecVersion": "<string>", 
   "ioticsDIDType": "<string>",
   "controller":  "<string>",
   "creator":  "<string>",
   "updateTime":  "<number>",
   "proof":  "<string>",
   "revoked":  "<boolean>",
   "authentication": "<array of RegisterPublicKey>",
   "publicKey": "<array of RegisterPublicKey>",
   "delegateAuthentication": "<array of RegisterDelegationProof>",
   "delegateControl": "<array of RegisterDelegationProof>",
   "metadata": "<Metadata>",
}

Metadata optional structure in the DiD document

{
  "label": "<optional string>",
  "comment": "<optional string>",
  "url": "<optional string>",
}

RegisterPublicKey structure for key used in authentication and publicKey in lists.

{
 "id": "<string>",
 "type": "<string>",
 "publicKeyBase58": "<string>",
 "revoked": "<optional boolean>"
}

RegisterDelegationProof structure on delegation.

{
"id": "<string>",
"controller": "<string>",
"proof": "<string>",
"revoked": "<optional boolean>",
}

Seed The object containing the seed

{
   "seed": "<string>. base58 encoded>",
} 

DiD A DiD ID

{
  "did": "<string>"
} 

DelegationData The data for the delegation that's been just created

{
 "did":            "<string>",
 "subjectType":    "<string. one of user, twin, agent>",
 "agentDid":       "<string>",
 "delegationName": "<string>", 
} 

CacheConfig Cache configuration object

 
{
   "ttlSec": "<integer, default 10 seconds>",
   "size": "<integer, default 128>"
}

Token Object containing a jwt token

{
  "token": "<jwt token string>"
}

The following functions are methods of the object IoticsIdentity:

/**
  * Creates a 256 bits seed encoded base58
  *
  * @returns Promise of: Seed | Error
  */
function createDefaultSeed()

/**
  * Creates the identity of an agent. It is idempotent, so if the identity exists, it won't be created, unless the option "override" is specified.
  * 
  * @param {String} resolverAddress
  * @param {CreateIdentityOption} identityOpts
  * @returns Promise of: DiD JSON or error JSON
  */
function createAgentIdentity(resolverAddress, identityOpts)

/**
  * Creates the identity of a user. It is idempotent, so if the identity exists, it won't be created, unless the option "override" is specified.
  * 
  * @param {String} resolverAddress
  * @param {CreateIdentityOption} identityOpts
  * @returns Promise of: DiD | Error
  */
function createUserIdentity(resolverAddress, identityOpts)

/**
  * Creates the identity of a twin. It is idempotent, so if the identity exists, it won't be created, unless the option "override" is specified.
  *
  * @param {String} resolverAddress
  * @param {CreateIdentityOption} identityOpts
  * @returns Promise of: DiD | Error
  */
function createTwinIdentity(resolverAddress, identityOpts)

/**
  * Retrieves the document from the resolver. 
  * 
  * @param {String} resolverAddress
  * @param {String} didId
  * @returns Promise of: DiD | Error
  */
function getRegisteredDocument(resolverAddress, didId) 

/**
  * 
  * Twin delegates control, with given name, to agent 
  * 
  * @param {String} resolverAddress 
  * @param {IdentityOptions} twinIdentityOpts 
  * @param {IdentityOptions} agentIdentityOpts 
  * @param {String} delegationName 
  * @returns Promise of: DelegationData | Error
  */
function delegateControl(resolverAddress, twinIdentityOpts, agentIdentityOpts, delegationName)

/**
  * User delegates authentication, with given name, to agent 
  * 
  * @param {String} resolverAddress 
  * @param {IdentityOptions} userIdentityOpts 
  * @param {IdentityOptions} agentIdentityOpts 
  * @param {String} delegationName 
  * @returns Promise of: DelegationData | Error
  */
function delegateAuthentication(resolverAddress, userIdentityOpts, agentIdentityOpts, delegationName)

/**
  * Creates a token to authenticate this agent on behalf of the user, to the "audience" endpoint. 
  * 
  * The token is valid for the given duration in milliseconds.
  * 
  * @param {IdentityOptions} agentIdentityOps 
  * @param {String} userDiD 
  * @param {Integer} durationMs 
  * @param {String} audience 
  * @returns Promise of: Token | Error
  */
function createAgentAuthToken(agentIdentityOps, userDiD, durationMs, audience) 

/** 
  * Configures cache holding known Identities. 
  * 
  * @param {CacheConfig} conf 
  * @returns Error | nil 
  */
function setIdentitiesCacheConfig(conf)

References

Thank you to:

• create-a-javascript-library-and-fully-automate-the-releases
• wasm: global functions from wasm not working from node
• how-to-bundle-your-library-for-both-nodejs-and-browser-with-webpack