README
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.
const authSecret = '0xabc123...' // a hex encoded secret
const idWallet = new IdentityWallet(getConsent, { authSecret })
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.
Link an address to the identity
Multiple blockchain addresses can be linked to an identity controlled by an IdentityWallet instance. Right now two types of ethereum addresses are supported: EOAs (externally owned accounts) and EIP1271 contracts. Support for other types and blockchains can be easily added by contributing to the 3id-blockchain-utils module. To link an address simply use the linkAddress method as shown in the example below. The ethProvider needs to be able to sign a message using personal_sign for the given address.
const ethAddress = '0xabc...'
const ethProvider = // an ethereum json-rpc provider
await idWallet.linkAddress(ethAddress, ethProvider)
Maintainers
API Documentation
IdentityWallet
Kind: global class
- IdentityWallet
- new IdentityWallet(getConsent, config)
- .get3idProvider() ⇒
ThreeIdProvider - .getDidProvider() ⇒
DidProvider - .hasConsent(spaces, origin) ⇒
Boolean - .getConsent(spaces, origin) ⇒
Boolean - .linkAddress(address, provider) ⇒
Object - .authenticate(spaces, opts) ⇒
Object - .isAuthenticated(spaces, origin) ⇒
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.externalAuth | String |
External auth function, directly returns key material, used to migrate legacy 3box accounts |
identityWallet.get3idProvider() ⇒ ThreeIdProvider
Get the 3IDProvider
Kind: instance method of IdentityWallet
Returns: ThreeIdProvider - The 3IDProvider for this IdentityWallet instance
identityWallet.getDidProvider() ⇒ DidProvider
Get the DIDProvider
Kind: instance method of IdentityWallet
Returns: DidProvider - The DIDProvider for this IdentityWallet instance
identityWallet.hasConsent(spaces, origin) ⇒ Boolean
Determine if consent has been given for spaces for a given origin
Kind: instance method of IdentityWallet
Returns: Boolean - True if consent has already been given
| Param | Type | Description |
|---|---|---|
| spaces | Array.<String> |
The desired spaces |
| origin | String |
Application domain |
| opt.address | String |
Optional address (managementKey) if keyring not available yet |
identityWallet.getConsent(spaces, origin) ⇒ Boolean
Get consent for given spaces for a given origin
Kind: instance method of IdentityWallet
Returns: Boolean - True consent was given
| Param | Type | Description |
|---|---|---|
| spaces | Array.<String> |
The desired spaces |
| origin | String |
Application domain |
| opt.address | String |
Optional address (managementKey) if keyring not available yet |
identityWallet.linkAddress(address, provider) ⇒ Object
Link a blockchain address to the identity. Usually the address would be an ethereum address (EOA or EIP1271 compatible contract) and the provider is an JSON-RPC provider that can sign a message with this address using personal_sign.
Kind: instance method of IdentityWallet
Returns: Object - The link proof object
| Param | Type | Description |
|---|---|---|
| address | String |
The address to link |
| provider | Object |
The provider that can sign a message for the given address |
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, origin) ⇒ 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 |
| origin | String |
Application domain |
| opt.address | String |
Optional address (managementKey) if keyring not available yet |
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.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.to | String |
The public key to encrypt the message to |
| 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, nonce, and ephemeralFrom for asymmetric encrypted objects) |
| space | String |
The space used for encryption |