ara-identity

Ara Identity is an implementation of DIDs, or Decentralized Identifiers, which allows users to interact with services in the Ara network. A DID document in JSON format is called a DDO (DID document object).

Table of Contents

• Status
• Stability
• Installation
• Usage
• API
• CLI
• Contributing
• See Also

Status

This project is in active development.

Stability

Stability: 1 - Experimental. These features are still under active development and subject to non-backwards compatible changes, or even removal, in any future version. Use of the feature is not recommended in production environments. Experimental features are not subject to the Node.js Semantic Versioning model.

Installation

$ npm install arablocks/ara-identity

Usage

const aid = require('ara-identity')
const context = require('ara-context')()

// Create an Ara ID
const createOpts = {
  context,
  password: 'hello'
}
const identity = aid.create(createOpts)

// Archive an Ara ID
const archiverOpts = {
  secret: 'test-secret',
  network: 'test-archiver',
  keyring: '~/.ara/keyrings/keyring.pub'
}
await aid.archive(identity, archiverOpts)

// Resolve an Ara ID to get DID-document
const resolverOpts = {
  secret: 'test-secret',
  network: 'test-resolver',
  keyring: '~/.ara/keyrings/keyring.pub'
}
const ddo = aid.resolve(identity.identifier, resolverOpts)

// Recover a lost Ara ID using a valid bip39 mnemonic
const recoverOpts = {
  mnemonic: 'glad kangaroo coyote rich detail grief matrix spirit jeans owner heart net',
  password: 'qwerty' // New password to be used for encryption of the identity files
}
const identity = aid.recover(recoverOpts)

API

All functions check for input validity, input correctness, and throw an error if checks do not pass.

• aid.archive(identity, opts)
• aid.create(opts)
• aid.update(identifier, opts)
• aid.save(identity)
• aid.createIdentityKeyPath(identity)
• aid.did.create(publicKey)
• aid.did.normalize(identifier, method)
• aid.ddo.create(opts)
• aid.fs
• aid.fs.writeFile(identifier, filename, buffer)
• aid.fs.readFile(identifier, filename)
• aid.fs.readdir(identifier)
• aid.fs.access(identifier, filename)
• aid.fs.lstat(identifier, filename)
• aid.fs.stat(identifier, filename)
• aid.list()
• aid.recover(opts)
• aid.replicate(did)
• aid.resolve(did, opts)
• aid.revoke(opts)
• aid.sign(identifier, message, opts)
• aid.verify(identifier, signature, message, opts)

aid.archive(identity, opts)

Archive an Ara ID into the Ara network where identity is the Ara Identity object created using create() method. See also Ara Identity Archiver.

const context = require('ara-context')()
const opts = {
  context,
  password: 'hello'
}
const identity = await aid.create(opts)

const archiverOpts = {
  secret: 'test-secret',
  network: 'test-archiver',
  keyring: '~/.ara/keyrings/keyring.pub',
  shallow: true
}

await aid.archive(identity, archiverOpts)

aid.create(opts)

Create an Ara identity encrypted using the provided password.

const context = require('ara-context')()

const opts = {
  context,
  password: 'hello'
}

const identity = await aid.create(opts)

aid.update(identifier, opts)

Updates an identity state. This recreates new signatures for an identity.

const opts = { password: 'hello' }
const identity = await aid.create(opts)
identity.ddo.addPublicKey(aPublicKeyToAdd)
identity.password = password // must include password updates
await aid.update(identity.did.did, identity.ddo)
await aid.save(identity)

aid.save(identity)

Save an Ara identity to disk. Does not work in browser.

const context = require('ara-context')()

const opts = {
  context,
  password: 'hello'
}

const identity = await aid.create(opts)
if (await aid.save(identity)) {
  console.log(await aid.resolve(identity))
}

aid.createIdentityKeyPath(identity)

Generate and retrieve the path to files of an identity stored locally

const context = require('ara-context')()
const opts = {
  context,
  password: 'hello'
}
const identity = await aid.create(opts)

const path = aid.createIdentityKeyPath(identity)

aid.did.create(publicKey)

Create a DID reference document from a given publicKey of a key pair.

const { publicKey, secretKey } = crypto.keyPair()

const didUri = did.create(publicKey)

aid.did.normalize(identifier, method)

Recreate a DID URI from an identifier and DID method.

const identifier = '4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'
const method = 'ara'

const didURI = aid.did.normalize(identifier, method)

console.log(didURI) // 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'

aid.ddo.create(opts)

Create a DID document for a given DID URI.

const { publicKey, secretKey } = crypto.keyPair()
const didUri = did.create(publicKey)
const opts = {
  id: didUri
}

const didDocument = ddo.create(opts)

aid.fs

aid.fs is an an abstract file system interface for reading and writing identity files for an identity on disk or from the network. It provides a familiar FS API exposing functions like readFile and writeFile. Most operations will use the fs module directly, but if a file is not found, it will ask the network for it. This allows services running on servers to bind themselves to identities, without the identity files living on the same machine. More information about remote servers can be found at archiver & resolver.

aid.fs.writeFile(identifier, filename, buffer)

Write a file to its local identity directory based on a given identifier.

const context = require('ara-context')()
const opts = {
  context,
  password: 'hello'
}
const identity = await aid.create(opts)
const files = identity.files

for (let i = 0; i < files.length; i++) {
  await aid.fs.writeFile(identity.identifier, files[i].path, files[i].buffer)
}

/*
Example resulting file structure:
0b86f22e88e1be3c243f3604981683a3f51808103c98bcf99b6b72cfe9646cc1/
├── ddo.json
├── identity
├── keystore
│   ├── ara
│   └── eth
└── schema.proto
*/

aid.fs.readFile(identifier, filename)

Read a file for a given identifier from its local copy or a remote server.

const did = 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'

const ddo = await aid.fs.readFile(did, 'ddo.json')

aid.fs.readdir(identifier)

Read the contents of the identity directory for a given identifier. The identity directory may be located on a remote server.

const did = 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'

const files = await aid.fs.readdir(did)
console.log(files) // Displays a list of all files present in that identity directory

• TODO: Verify method definition to meet with method naming (prashanth)

aid.fs.access(identifier, filename)

Check if a file is present in the identity directory of a given identifier. The identity directory may be located on a remote server.

const did = 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'
try {
  if( await aid.fs.access(did, 'ddo.json') ) {
    console.log('ddo.json file is present')
  }
} catch(err) {
  throw new Error(err)
}

aid.fs.lstat(identifier, filename)

Retrieve information about a file from the identity directory of a given identifier. The identity directory may be located on a remote server. Throws error if file is not found. Note: This function does not follow symlinks.

const did = 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'

const stats = await aid.fs.lstat(did, 'ddo.json')
* TODO: put example print out here.

aid.fs.stat(identifier, filename)

Retrieve information about a file from the identity directory of a given identifier. The identity directory may be located on a remote server. Throws error if file is not found. This function will follow symlinks.

const did = 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'

const stats = await aid.fs.stat(did, 'ddo.json')
* TODO: put example print out here.

aid.list([path])

Return a list all identities present locally in a given path. path defaults to env root path if no path is provided. See ara-runtime-configuration docs for more information about environment variables.

const identities = await list()
* TODO: put example print out here.

aid.recover(opts)

Recover a lost Ara identity by providing the valid bip39 mnemonic returned during creation.

const context = require('ara-context')()

const opts = {
  context,
  password: 'password',
  mnemonic: 'glad kangaroo coyote rich detail grief matrix spirit jeans owner heart net'
}

const identity = await aid.recover(opts)

aid.replicate(did)

Replicate all identity files of a given Ara ID as a Buffer array from a remote server. Note: Ensure .ararc file contains entries to the DNS & DHT server of the remote node.

const did = 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'
const identityFiles = await aid.replicate(did)

aid.resolve(did, opts)

Return the DID document of an Ara ID from a local copy or a remote server. See Ara Identity Resolver for more information.

const did = 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'
const opts = {
  secret: 'test-secret',
  network: 'resolver',
  keyring: '~/.ara/keyrings/keyring.pub'
}
const ddo = await aid.resolve(did, opts)
* TODO: put example print out here. (DID document in JSON format)

aid.revoke(opts)

Revoke an Ara ID using the the valid bip39 mnemonic returned during creation. This action cannot be reverted. Note: Please archive your identity after revoking to publish changes into the ara network.

const context = require('ara-context')()
const opts = {
  context,
  mnemonic: 'glad kangaroo coyote rich detail grief matrix spirit jeans owner heart net',
  password: 'password'
}
const revokedIdentity = await aid.revoke(opts)

aid.sign(identifier, message, opts)

const message = Buffer.from()'hello')
const password = Buffer.from('password')
const identifier = 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'
const signature = await aid.sign(identifier, message, { password })

aid.verify(identifier, signature, message, opts)

const message = Buffer.from('hello')
const password = Buffer.from('password')
const identifier = 'did:ara:4d7eba2809e627168054cae10a3a08fbdb9f5d58cd0e26a565c1c14c4157cb45'
const signature = await aid.sign(identifier, message, { password })
const verified = await aid.verify(identifier, signature, message)

CLI

See CLI Readme to use ara-identity from the command line.

Contributing

• Commit message format
• Commit message examples
• How to contribute
• Release Versioning guidelines

See Also

• W3C Decentralized ID specs
• Ara Identity Archiver
• Ara Identity Resolver
• Ara Context
• ara-crypto
• ara-context

License

LGPL-3.0