@mc3-aether/identity-wallet v1.4.2
Identity Wallet
š-wallet
IdentityWallet is a JavaScript SDK that allows developers to create and manage UPI identities on the Ceramic network. It exposes a DID Provider interface which exposes JOSE signing and decryption though a JOSN-RPC interface. IdentityWallet can be used in combination with js-did.
Getting Started
Installation
Install the identity wallet 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 getPermission
function
the getPermission
configuration parameter is always required when creating an instance of IdentityWallet. It is used to give an application permission to decrypt and sign 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 paths.
The function is called with one parameter which is the request
object. It looks like this:
{
type: 'authenticate',
origin: 'https://my.app.origin',
payload: {
paths: ['/path/1', '/path/2']
}
}
In the above example the app with origin https://my.app.origin
is requesting access to /path/1
and /path/2
. If the user consents to this the function should just return the paths
array, otherwise an empty array. Note that an array containing only some of the requested paths may also be returned.
Creating a wallet with an authentication method
To create a wallet with an auth method you can pass two params to the create method of IDW as shown below. If the auth method doesn't have a UPI associated with it yet IDW will create a new UPI.
const authSecret = new Uint8Array([ ... ]) // Entropy used to authenticate
const authId = 'myAuthenticationMethod' // a name of the auth method
const idWallet = await IdentityWallet.create({ getPermission, authSecret, authId })
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 = await IdentityWallet.create({ getPermission, seed })
Using the IdentityWallet with js-did
An instance of the DID provider from IdentityWallet can be passed directly to js-did.
const provider = idWallet.getDidProvider()
const did = new DID({ provider })
Maintainers
API Documentation
IdentityWallet
Kind: global class
- IdentityWallet
- new IdentityWallet()
- instance
- .keychain
- .permissions
- .id
- .getDidProvider() ā DidProvider
- .resetIDX()
- static
new IdentityWallet()
Use IdentityWallet.create() to create an IdentityWallet instance
identityWallet.keychain
Kind: instance property of IdentityWallet
Properties
Name | Type | Description |
---|---|---|
keychain | Keychain | Edit the keychain |
identityWallet.permissions
Kind: instance property of IdentityWallet
Properties
Name | Type | Description |
---|---|---|
permissions | Permissions | Edit permissions |
identityWallet.id
Kind: instance property of IdentityWallet
Properties
Name | Type | Description |
---|---|---|
id | string | The DID of the IdentityWallet instance |
identityWallet.getDidProvider() ā DidProvider
Get the DIDProvider
Kind: instance method of IdentityWallet
Returns: DidProvider - The DIDProvider for this IdentityWallet instance
identityWallet.resetIDX()
Reset the IDX doc structure to a default (mostly empty) state.
Kind: instance method of IdentityWallet
IdentityWallet.create(config) ā IdentityWallet
Creates an instance of IdentityWallet
Kind: static method of IdentityWallet
Returns: IdentityWallet - An IdentityWallet instance
Param | Type | Description |
---|---|---|
config | Object | The configuration to be used |
config.getPermission | function | The function that is called to ask the user for permission |
config.seed | Uint8Array | The seed of the identity, 32 bytes |
config.authSecret | Uint8Array | The authSecret to use, 32 bytes |
config.authId | String | The authId is used to identify the authSecret |
config.disableIDX | Boolean | Disable creation of the IDX document |
config.v03ID | String | A v0 UPI, has to be passed if a migration is being preformed |
Keychain
Kind: global class
- Keychain
- new Keychain()
- .list() ā Array.<string>
- .add(authId, authSecret)
- .remove(authId)
- .status() ā KeychainStatus
- .commit()
new Keychain()
The Keychain enables adding and removing of authentication methods.
keychain.list() ā Array.<string>
List all current authentication methods.
Kind: instance method of Keychain
Returns: Array.<string> - A list of authIds.
keychain.add(authId, authSecret)
Add a new authentication method (adds to staging).
Kind: instance method of Keychain
Param | Type | Description |
---|---|---|
authId | String | An identifier for the auth method |
authSecret | Uint8Array | The authSecret to use, should be of sufficient entropy |
keychain.remove(authId)
Remove an authentication method (adds to staging).
Kind: instance method of Keychain
Param | Type | Description |
---|---|---|
authId | String | An identifier for the auth method |
keychain.status() ā KeychainStatus
Show the staging status of the keychain. Since removing auth methods will rotate the keys of the UPI its a good idea to remove multiple auth methods at once if desired. Therefore we introduce a commit pattern to do multiple updates to the keychain at once.
Kind: instance method of Keychain
Returns: KeychainStatus - Object that states the staging status of the keychain
keychain.commit()
Commit the staged changes to the keychain.
Kind: instance method of Keychain
Permissions
Kind: global class
- Permissions
- new Permissions()
- .request(origin, paths) ā Array.<String>
- .has(origin, paths) ā Boolean
- .get(origin) ā Array.<String>
- .set(origin, paths)
new Permissions()
The Permissions class exposes methods to read and update the given permissions
permissions.request(origin, paths) ā Array.<String>
Request permission for given paths for a given origin.
Kind: instance method of Permissions
Returns: Array.<String> - The paths that where granted permission for
Param | Type | Description |
---|---|---|
origin | String | Application domain |
paths | Array.<String> | The desired paths |
permissions.has(origin, paths) ā Boolean
Determine if permission has been given for paths for a given origin.
Kind: instance method of Permissions
Returns: Boolean - True if permission has previously been given
Param | Type | Description |
---|---|---|
origin | String | Application domain |
paths | Array.<String> | The desired paths |
permissions.get(origin) ā Array.<String>
Get the paths which the given origin has permission for.
Kind: instance method of Permissions
Returns: Array.<String> - The permissioned paths
Param | Type | Description |
---|---|---|
origin | String | Application domain |
permissions.set(origin, paths)
Set the paths which the given origin should have permission for.
Kind: instance method of Permissions
Param | Type | Description |
---|---|---|
origin | String | Application domain |
paths | Array.<String> | The desired paths |