Introducing, IdentityWallet SDK

Native 3Box identity and data authorization for wallets

Native 3Box Support for Crypto Wallets

We’re thrilled to announce that today we are lifting the curtain on our brand new IdentityWallet SDK, a JavaScript SDK that allows crypto wallets to natively integrate with the 3ID protocol. 3ID provides a standard way for wallets to handle user data authorization, signing, encryption, and decryption functionalities. With IdentityWallet, these functions can now occur directly inside the wallet, instead of being outsourced to a 3Box.js client running in a web browser.

Getting Started with IdentityWallet

• Read the Docs 📚

Why IdentityWallet?

By separating the IdentityWallet SDK identity and authorization functionalities from 3Box SDK, we can make the 3Box system much more modular. Additional benefits of this model include support for a wider range of application architectures, smart contract accounts, and improved security.

More Application Architectures ⚙️

Support react native mobile crypto wallets. We have separated out the core identity, signing, and encryption functionalities needed to perform basic data access control operations. This allows us to remove IPFS and other dependencies from IdentityWallet which have not worked on react native.

Support for node.js applications. With this new modular architecture, it is easy to run 3Box with server-side applications.

Support more transport methods between 3Box-enabled wallets and web apps. Since we have separated IdentityWallet (wallets) from 3Box SDK (apps), data authorization requests can be transported over a variety of protocols such as WalletConnect.

Smart Contract Accounts ✨

Support Ethereum smart contract accounts. Many Ethereum wallets are moving to a smart contract based user model, which uses many different device keys for authentication. With IdentityWallet, we can add all those keys as authentication methods to the users 3Box. To achieve this we are implementing the EIP-1271 standard.

Improved Security 🔐

Improve security of 3Box keys. 3Box keys used for signing and encryption can now be safely kept inside the wallet, instead of in the user’s browser localStorage where they are more vulnerable.

How does IdentityWallet work?

IdentityWallet consists of three distinct components, that together allow an IdentityWallet client running in one context to perform identity and data authorization functions and transport them back to a 3Box.js client.

• IdentityWallet SDK: A JavaScript client SDK that can run on crypto wallets running in react native on mobile or JavaScript on web
• 3ID Protocol: The decentralized identity, authentication, encryption, and access control protocol used throughout in the 3Box system
• 3ID JSON-RPC interface: Facilitates communication between the IdentityWallet SDK and the 3Box.js SDK

How to integrate with IdentityWallet

This section describes how to integrate with IdentityWallet if you’re building a crypto wallet. IdentityWallet currently only supports JavaScript, so it will work for web wallets and react native wallets. We’re working on extending IdentityWallet to be more compatible with iOS and Android/Kotlin.

If you’re building a web application, nothing changes for you. You can still just use the 3Box.js SDK as you always have.

1. Install IdentityWallet SDK

Getting started with IdentityWallet SDK is simple. Just follow these two steps:

First, install the identity-wallet package.

Install IdentityWallet in your npm project:

$ npm install identity-wallet

Then, import the IdentityWallet module.

Import IdentityWallet into your project using one of the following methods:

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>

Load a remote copy from unpkg CDN

<!-- The most recent version  -->
<script src="https://unpkg.com/3box/dist/identity-wallet.js"></script>
<!-- The most recent minified version  -->
<script src="https://unpkg.com/3box/dist/identity-wallet.min.js"></script>
<!-- Load specific versions by specifying the version as follows -->
<script src="https://unpkg.com/3box@<version>/dist/identity-wallet.js"></script>

2. Create an IdentityWallet instance

All 3Box accounts have a 3ID identity that they use to authorize and encrypt/decrypt data. In order to authorize, access, and update data saved in a 3Box, you will need to generate an IdentityWallet instance which contains the user’s 3ID. There are two primary ways to accomplish this; choose the correct one for your use case:

Generate an IdentityWallet from a Seed

You should consider generating an IdentityWallet from a seed if your wallet implements a traditional cryptographic key-pair account model.

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({ seed })

This is best for…

• Keypair account-based wallets
• Node.js applications
• Web applications with hosted wallets

Create an IdentityWallet for a Contract Account

You should consider creating an IdentityWallet this way if your wallet implements a contract-based user account mode. This will allow you to associate multiple signing/authentication accounts to the same user identity.

For wallets which doesn’t have key-pair accounts/identities, 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({ authSecret, ethereumAddress })

This is best for…

• Smart contract-based wallets
• Sharing 3Box data across multiple signing/auth/eth accounts and contracts

3. Pass the 3IDProvider to apps

Now that you have created an IdentityWallet instance in the previous step, you will need to provide this IdentityWallet instance to the 3Box SDK (“the client”). There are a few ways to accomplish this depending on your use case and application context.

Option 1: The application contains a wallet

If the application contains a wallet, the wallet should directly pass the IdentityWallet instance to the openBox() method in the 3Box SDK.

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

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

This option is particularly useful for:

• Wallets that directly integrate the 3Box SDK
• Applications that use 3Box SDK server-side

Example Use Case for IDW Option 1: If a wallet, such as the MetaMask browser extension, is interested in supporting IdentityWallet in addition to allowing users to upload and modify 3Box data from directly inside the wallet instead of sending them to a web app to perform these functions. For example, they may want to allow users to create/edit a profile, store/backup data, message users, and more.

Option 2: The browser can access both the wallet and the application

If the browser can separately access both the wallet and the application, then the browser should inject the 3IDProvider directly into the application.

You would use this if you are a wallet provider that wants to allow external applications to access 3Box signing functionality and the 3ID protocol managed inside the wallet.

This option is particularly useful for:

• Web apps on a mobile dapp browser (Opera, Rainbow, MetaMask mobile)
• Web apps on a desktop dapp browser (Brave)
• Web apps that use a desktop browser wallet extension (MetaMask extension, Dapper)
• Web apps that use an iFrame-based wallet (Portis)

Example Use Case for IDW Option 2: If a wallet, such as the MetaMask browser extension, wants to allow external web-based applications to access 3Box signing functionality and the 3ID protocol managed inside the wallet, they would implement Option 2.

Option 3: The wallet and application exist in separate browsers or devices

If the wallet and the application exist in separate browsers or devices, then the wallet should pass its IdentityWallet instance (3IDProvider) to 3Box SDK running in the application using another transport mechanism, such as WalletConnect.

This option is particularly useful for:

• Node.js apps that use 3Box
• Mobile apps that don’t have a built in wallet
• Browser applications that use a desktop or mobile wallet

Example Use Case for IDW Option 3: If a mobile wallet/signer wants to allow desktop web applications to access 3Box signing functionality and the 3ID protocol managed inside the wallet, they would implement Option 3.

4. Respond to app requests

Now that your wallet has passed the 3IDProvider to the application in the previous step, the application will now be able to send requests to the wallet over the 3ID JSON-RPC API.

These requests ask the wallet to perform actions on behalf of the user including data authentication, encryption, decryption, sign, and more. Jump to the next section to learn more about the methods available in the IdentityWallet API.

These 3ID requests need consent UI! We don’t yet have out-of-the-box wallet UI for IdentityWallet API methods, so you may need to implement a few basic signature screens in your wallet to visually communicate these requests to the user.

Explore the JSON-RPC Interface

The 3ID JSON-RPC interface describes all functions needed by the 3box.js client when interacting with a 3ID identity. The IdentityWallet SDK will natively support these functions, making it easy for wallets to add 3ID support.

The interface defines the following methods:

• 3id_authenticate: Method for authenticating to get access to the requested spaces.
• 3id_isAuthenticated: Checks if the user has already authenticated this app. If no spaces are given as parameters it just checks if the main account is authenticated.
• 3id_signClaim: Signs a claim with the desired DID. The format of the signed claim is a JWT.
• 3id_encrypt: Encrypt a message with the desired space encryption keys. If the to parameter is not passed the message will be symmetrically encrypted.
• 3id_decrypt: Decrypt a message with the desired space encryption keys.
• 3id_hashEntryKey: Hashes the given key with a salt only known to the specific 3ID.
• 3id_newAuthMethodPoll: A poll method to get any new authData.

For more specifics on the 3ID JSON-RPC interface, view our API Docs.

Questions? Reach out on Discord!

We’re always online and available to chat in Discord if you have any questions about using IdentityWallet or anything else. See you there!