iotics-identity-js v0.0.1
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
- Not all APIs have been mapped
- In nodejs, functions are exported in the global namespace - maybe there's a better way
- node is using active wait to pause for 1500ms to wait for the functions to be loaded in the js global.
Known Issues
- Golang wasm compiles net/http client using
fetch
so, in nodenode-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: