Identity Wallet

🆔-wallet

3Box identity-wallet-js is a JavaScript SDK that allows Ethereum JavaScript wallet developers to natively support 3Box identity and authentication functionalities, including: creating 3Box accounts, adding authentication methods (Ethereum keys), and responding to authentication requests for 3Box accounts as well as spaces.

Getting Started

Installation

Install 3box in your npm project:

$ npm install identity-wallet

Usage

Import Identity Wallet into your project

Import the identity-wallet module

const IdentityWallet = require('identity-wallet')

Import using the dist build in your html code

<script type="text/javascript" src="../dist/identity-wallet.js"></script>

Understanding the getConsent function

The first parameter of the IdentityWallet constructor is the getConsent function. This function determines whether or not any given origin (app) is allowed access to the users data. What this function should do is to present a dialog to the user in the wallet UI, asking for permission to access the given spaces.

The function is called with one parameter which is the request object. It looks like this:

{
  type: 'authenticate',
  origin: 'https://my.app.origin',
  spaces: ['space1', 'space2']
}

In the above example the app with origin https://my.app.origin is requesting access to space1 and space2. If the user consents to this the function should return true, otherwise it should return false. Note that if the spaces array is empty the app is requesting access to the general 3Box storage.

Creating a wallet with a seed

To create a wallet with a seed you can simply pass it as an option to the constructor. This will create an instance of the IdentityWallet that derives all it's keys from this seed. Be careful, if this seed is lost the identity and all of it's data will be lost as well.

const seed = '0xabc123...' // a hex encoded seed

const idWallet = new IdentityWallet(getConsent, { seed })

Creating an identity for a contract wallet

For wallets which doesn't have one keypair, e.g. smart contract wallets, we provide a way of creating an identity with multiple authentication secrets. In this model each authentication secret grants full access to the identity. To create an instance of the IdentityWallet in this way the ethereum address of the account also needs to be passed to the constructor.

const authSecret = '0xabc123...' // a hex encoded secret
const ethereumAddress = '0xabc123' // an ethereum address

const idWallet = new IdentityWallet(getConsent, { authSecret, ethereumAddress })

New authentication secrets can later be added by calling the addAuthMethod instance method of the identityWallet. Note that this method can only be called after an authentication first has happened (Box.openBox has been called from 3box-js).

const authSecret2 = '0xabc123...' // a hex encoded secret

idWallet.addAuthMethod(authSecret2)

Using the IdentityWallet with 3box-js

An instance of IdentityWallet can be passed directly to 3box-js and will be used to authenticate the user.

const provider = idWallet.get3idProvider()
const box = await Box.openBox(null, provider)

Using the ThreeIdProvider to consume RPC calls

As described above the 3idProvider can be accessed by calling idWallet.get3idProvider(). The provider object that is returned can be used to consume 3ID JSON-RPC requests.

const provider = idWallet.get3idProvider()
// using the provider
const response = await provider.send(rpcRequest, origin)

// alternatively using a callback function
provider.send(rpcRequest, origin, (error, response) => {
  // use response or handle error
})

In the above example rpcRequest is a request formated according to the 3ID JSON-RPC specification, and origin is a string, e.g. https://my.app.origin.

API Documentation

IdentityWallet

Kind: global class

• IdentityWallet
  • new IdentityWallet(getConsent, config)
  • .get3idProvider() ⇒ ThreeIdProvider
  • .authenticate(spaces, opts) ⇒ Object
  • .isAuthenticated(spaces) ⇒ Boolean
  • .addAuthMethod(authSecret)
  • .signClaim(payload, opts) ⇒ String
  • .encrypt(message, space, opts) ⇒ Object
  • .decrypt(encryptedObject, space) ⇒ String

new IdentityWallet(getConsent, config)

Creates an instance of IdentityWallet

Returns: this - An IdentityWallet instance

Param	Type	Description
getConsent	function	The function that is called to ask the user for consent
config	Object	The configuration to be used
config.seed	String	The seed of the identity, 32 hex string
config.authSecret	String	The authSecret to use, 32 hex string
config.ethereumAddress	String	The ethereumAddress of the identity

identityWallet.get3idProvider() ⇒ ThreeIdProvider

Get the 3IDProvider

Kind: instance method of IdentityWallet
Returns: ThreeIdProvider - The 3IDProvider for this IdentityWallet instance

identityWallet.authenticate(spaces, opts) ⇒ Object

Authenticate to given spaces

Kind: instance method of IdentityWallet
Returns: Object - The public keys for the requested spaces of this identity

Param	Type	Description
spaces	Array.<String>	The desired spaces
opts	Object	Optional parameters
opts.authData	Array.<Object>	The authData for this identity

identityWallet.isAuthenticated(spaces) ⇒ Boolean

Check if authenticated to given spaces

Kind: instance method of IdentityWallet
Returns: Boolean - True if authenticated

Param	Type	Description
spaces	Array.<String>	The desired spaces

identityWallet.addAuthMethod(authSecret)

Add a new authentication method for this identity

Kind: instance method of IdentityWallet

Param	Type	Description
authSecret	String	A 32 byte hex string used as authentication secret

identityWallet.signClaim(payload, opts) ⇒ String

Sign a verifiable credential. The format of the credential is did-jwt.

Kind: instance method of IdentityWallet
Returns: String - The signed claim encoded as a JWT

Param	Type	Description
payload	Object	The payload of the claim
opts	Object	Optional parameters
opts.DID	String	The DID used as the issuer of this claim
opts.space	String	The space used to sign the claim
opts.expiresIn	String	Set an expiry date for the claim as unix timestamp

identityWallet.encrypt(message, space, opts) ⇒ Object

Encrypt a message

Kind: instance method of IdentityWallet
Returns: Object - The encrypted object (ciphertext and nonce)

Param	Type	Description
message	String	The message to be encrypted
space	String	The space used for encryption
opts	Object	Optional parameters
opts.nonce	String	The nonce used to encrypt the message
opts.blockSize	String	The blockSize used for padding (default 24)

identityWallet.decrypt(encryptedObject, space) ⇒ String

Decrypt a message

Kind: instance method of IdentityWallet
Returns: String - The decrypted message

Param	Type	Description
encryptedObject	Object	The encrypted object (ciphertext and nonce)
space	String	The space used for encryption