Repository files navigation

3box.js and related tools built by 3Box Labs are deprecated and no loger supported. Developers are encurraged to build withhttps://ceramic.network which is a more secure and decentralized protocol for sovereign data.

Install |Usage |Example |Data Standards |API Docs

⚠️ 3Box.js is slowly being phased out in favor of a new more decentralized system called IDX (https://idx.xyz) which is built on top of the Ceramic network. You can use 3Box.js for now, but be aware that support will be limited as Ceramic is moving closer to a mainnet release.

This is a library which allows you to set, get, and remove private and public data associated with an ethereum account. It can be used to store identity data, user settings, etc. by dapps that use a web3 enabled browser. The data will be retrievable as long as the user has access to the private key for the used ethereum account. The data is encrypted and can not be read by any third party that the user hasn't authorized. There is one shared space for data which all authorized dapps access by default, then there are spaces which dapps have to request explicit consent to access.

Install 3box in your npm project:

$ npm install 3box

Import the 3box module

constBox=require('3box')

Import using the dist build in your html code

<scripttype="text/javascript"src="../dist/3box.js"></script>

Or optionally by loading remote copy fromunpkg CDN.

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

3Box allows users to create a public profile for their Ethereum address. In your dapp you might have multiple ethereum addresses that you would like to display a name, image, and other basic social metadata for. ThegetProfile method allows you to fetch the public profile of any ethereum address (if it has one). This is astatic method so you can call it directly from theBox object.

constprofile=awaitBox.getProfile('0x12345abcde')console.log(profile)

3Box allows applications to create, read, update, and delete public and private data stored in a user's 3Box. To enable this functionality, applications must first authenticate the user's 3Box by calling theauth method. This method prompts the user to authenticate (sign-in) to your dapp and returns a promise with a threeBox instance. You can only update (set, get, remove) data for users that have authenticated to and are currently interacting with your dapp. BelowethereumProvider refers to the object that you would get fromweb3.currentProvider, orwindow.ethereum.

To create a 3Box session you call thecreate method. This creates an instance of the Box class which can be used to openThreads and authenticate the user in any order. This is best to call on page load, so it can begin initializing and connecting services like IPFS in background.

constbox=awaitBox.create()

Calling theauth method will authenticate the user. If you want to authenticate the user to one or multiple spaces you can specify this here. A provider needs to be passed, this can be anethereum provider (fromweb3.currentProvider, orwindow.ethereum) or a3ID Provider (fromIdentityWallet). If using an ethereum provider you need to pass an ethereum address to theauth method as well. If the user does not have an existing 3Box account, this method will automatically create one for them in the background.

constaddress='0x12345abcde'constspaces=['myDapp']awaitbox.auth(spaces,{ address, provider})

When you first authenticate the box in your dapp all data might not be synced from the network yet. You should therefore wait for the data to be fully synced. To do this you can simply await thebox.syncDone promise:

awaitbox.syncDone

This will allow you to know when all the user's data is available to you. We advise againstsetting any data before this sync has happened. However, reading data before the sync is complete is fine and encouraged - just remember to check for updates once the sync is finished! Please note,box.syncDone can only be called once the user has been authenticated, it is not possible if only theBox.create method has been called.

If you prefer to not use promises you can add a callback using theonSyncDone method.

You can now use thebox instance object to interact with public and private data stored in the user's profile. In both the public and the private data store you use akey to set avalue.

// use the public profile// getconstnickname=awaitbox.public.get('name')console.log(nickname)// setawaitbox.public.set('name','oed')// removeawaitbox.public.remove('name')// use the private store// getconstemail=awaitbox.private.get('email')console.log(email)// setawaitbox.private.set('email','oed@email.service')// removeawaitbox.private.remove('email')

constfields=['name','website','employer']constvalues=['Jon Schwartz','openworklabs.com','Open Work Labs']awaitbox.public.setMultiple(fields,values)constprivateFields=['age','coinBalance']constprivateValues=['xxx','yyy']awaitbox.private.setMultiple(privateFields,privateValues)

Once you have created a 3Box session you can open a thread to view data in it. This can be done before you authenticate the user (required for them to post in the thread).When opening a thread the moderation options need to be given. You can passfirstModerator, a 3ID (or ethereum address) of the first moderator, and amembers boolean which indicates if it is a members thread or not.

constthread=awaitbox.openThread('myDapp','myThread',{firstModerator:'did:3:bafy...',members:true})

Once a thread has been opened you can call thegetPosts() method to retrive the posts.

A space is a named section of a users 3Box. Each space has both a public and a private store, and for every space you open the user has to grant explicit consent to view that space. This means that if your dapp uses a space that no other dapp uses, only your dapp is allowed to update the data and read the private store of that particular space. To open a space callednarwhal you simply call:

constspace=awaitbox.openSpace('narwhal')

Similarly to how you need to wait for data to sync in a users main data storage, you may also do the same thing for a space:

awaitspace.syncDone

Interacting with data in a space is done in the same way as interacting withbox.public andbox.private (see here). For example:

constconfig=awaitspace.private.get('dapp-config')

Threads are a shared datastore that enable decentralized communication between users, by allowing one or more users to post messages in a sequence. This functionality is great for adding commenting, chat, messaging, feed, and stream features to your application. Threads are saved within a space and users that join a thread (with the same name, space, moderation configs, and access configs) will be able to communicate in that thread.

For the fully detailed spec, view thedocumentation.

You can get all posts made in a public thread without opening a space. This is great for allowing visitors of your site view comments made by other users. This is achieved by calling thegetThread method on the Box object. A thread can be referenced by all its configuration options or by its address.

constposts=awaitBox.getThread(spaceName,threadName,firstModerator,membersThread)console.log(posts)

Threads can also be viewed without opening space, or authenticating by calling thegetPosts() method on the thread object returned fromopenThread (see Open a thread section above).

constposts=awaitBox.getThreadByAddress(threadAddress)console.log(posts)

However if applications want to add interactivity to the thread, such as allowing the user to post in a thread or follow updates in a thread, you will need to open their space to enable additional functionality. Same is true for a confidential thread, which requires you autheticate to get access to view the posts in a confidential thread.

To create and join a public thread, you can simply join the thread. This will implicitly use the moderation options where the current user is thefirstModerator andmembers is false.

constthread=awaitspace.joinThread('myThread')

A thread can also be given the moderation options when joining. You can passfirstModerator, a 3ID of the first moderator, and amembers boolean which indicates if it is a members thread or not. Moderators can add other moderators, add members, and delete any posts in the thread. Members can post in member only threads.

constthread=awaitspace.joinThread('myThread',{firstModerator:'some3ID',members:true})

To create and join a confidential thread.

constthread=awaitspace.createConfidentialThread('myConfThread')

At creation you will likely want to add other members so that they can read and write messages to the thread, as shown below.

An existing public or confidential thread can be joined by its address. Confidential threads are best referenced by their address.

constthread=awaitspace.joinThreadByAddress('/orbitdb/zdpuAp5QpBKR4BBVTvqe3KXVcNgo4z8Rkp9C5eK38iuEZj3jq/3box.thread.testSpace.testThread')

While public threads can be joined by address or by passing known configs (same as above).

constpublicThread=awaitspace.joinThread('myThread',{firstModerator:'some3ID',members:true})

An address of a thread can be found as follows once joined.

constthreadAddress=thread.address

This allows the user to add a message to the thread. The author of the message will be the user's 3Box DID. When a user posts in a thread, they are automatically subscribed to the thread and it is saved in the space used by the application under the keythread-threadName.

awaitthread.post('hello world')

This allows applications to get the posts in a thread.

constposts=awaitthread.getPosts()console.log(posts)

This allows applications to listen for new posts in the thread, and perform an action when this occurs, such as adding the new message to the application's UI.

thread.onUpdate(myCallbackFunction)

Add a moderator and list all existing moderators

awaitthread.addModerator('some3ID')constmods=awaitthread.listModerators()

Add a member and list all existing members, if a members only thread

awaitthread.addMember('some3ID')constmembers=awaitthread.listMembers()

Listen for when there has been moderators or member added.

thread.onNewCapabilities(myCallbackFunction)

You can quickly run and interact with some code by looking at the files in the/example folder. You run the example with the following commands:

$ npm ci$ npm run example:start

This runs a simple server athttp://localhost:3000/ that serves the staticexample/index.html file. This allows it easily interact with metamask. You can edit theexample/index.html file to try differnt code.

If you only want to fetch profile data from 3Box's profile APIs you can optimize by importing only those functions or the API specific dist file. Since this includes minimal dependencies, file size is ~ 80kb vs 4+mb for the full build.

const{ profileGraphQL, getProfile, getProfiles, getVerifiedAccounts}=require('3box/lib/api')

<scriptsrc="https://unpkg.com/3box/dist/3box.api.min.js"></script>

Some platforms, tooling, or configs have caused the build process to throw out of memory errors. This is a combination of the size of our library (plus dependencies) and the specific configs you have for your build. It could be things like tooling running on dependencies and not just your source or dependencies be recursively resolved. You can attempt to build the library anyways by adding the follow environment variable to increase memory for the node process.

NODE_OPTIONS=--max_old_space_size=4096 npm run build

Dapps can store data about users that relate to only their dapp. However we encurage dapps to share data between them for a richer web3 experience. Therefore we have createdKey Conventions in order to facilitate this. Feel free to make a PR to this file to explain to the community how you use 3Box!

Use theidUtils module tovalidate claims. Seethedid-jwt library for more details.

const{ idUtils}=require('3box')constclaim='eyJ0eX...'idUtils.verifyClaim(claim).then(valid=>console.info('details:',valid).catch(err=>console.error('claim verification failed:',err)

@oed

Kind: global class
Extends:BoxApi

• Box ⇐BoxApi
  • new Box()
  • instance
    • .public
    • .private
    • .verified
    • .spaces
    • .syncDone
    • .DID
    • .auth(spaces, opts)
    • .openSpace(name, opts) ⇒Space
    • .openThread(space, name, opts) ⇒Thread
    • .onSyncDone(syncDone) ⇒Promise
    • .linkAddress([link])
    • .removeAddressLink(address)
    • .isAddressLinked([query])
    • .listAddressLinks() ⇒Array
    • .logout()
  • static
    • .idUtils
      • .verifyClaim ⇒Object
      • .isSupportedDID(did) ⇒* |boolean
      • .isClaim(claim, opts) ⇒Promise.<boolean>
    • .create(provider, opts) ⇒Box
    • .supported() ⇒Boolean
    • .openBox(address, provider, opts) ⇒Box
    • .isLoggedIn(address) ⇒Boolean
    • .getIPFS() ⇒IPFS

Please use theopenBox method to instantiate a 3Box

Kind: instance property ofBox
Properties

Kind: instance property ofBox
Properties

Kind: instance property ofBox
Properties

Kind: instance property ofBox
Properties

Kind: instance property ofBox
Properties

Kind: instance property ofBox
Properties

Authenticate the user

Kind: instance method ofBox

Opens the space with the given name in the users 3Box

Kind: instance method ofBox
Returns:Space - the Space instance for the given space name

Open a thread. Use this to start receiving updates

Kind: instance method ofBox
Returns:Thread - An instance of the thread class for the joined thread

Sets the callback function that will be called once when the box is fully synced.

Kind: instance method ofBox
Returns:Promise - A promise that is fulfilled when the box is syned

Creates a proof that links an ethereum address to the 3Box account of the user. If given proof, it will simply be added to the root store.

Kind: instance method ofBox

Remove given address link, returns true if successful

Kind: instance method ofBox

Checks if there is a proof that links an external account to the 3Box account of the user. If not params given and any link exists, returns true

Kind: instance method ofBox

Lists address links associated with this 3Box

Kind: instance method ofBox
Returns:Array - An array of link objects

Closes the 3box instance and clears local cache. If you call this,users will need to sign a consent message to log in the next timeyou call openBox.

Kind: instance method ofBox

A module to verify & validate claims

Kind: static property ofBox

• .idUtils
  • .verifyClaim ⇒Object
  • .isSupportedDID(did) ⇒* |boolean
  • .isClaim(claim, opts) ⇒Promise.<boolean>

Verify a claim and return its content.Seehttps://github.com/uport-project/did-jwt/ for more details.

Kind: static property ofidUtils
Returns:Object - The validated claim

Check whether a string is a muport did or not

Kind: static method ofidUtils
Returns:* |boolean - Whether the did is a supported did or not

Check whether a string is a valid claim or not

Kind: static method ofidUtils
Returns:Promise.<boolean> - whether the parameter is an actual claim

Creates an instance of 3Box

Kind: static method ofBox
Returns:Box - the 3Box session instance

Determines if this browser environment supports 3boxjs and ipfs.

Kind: static method ofBox

Opens the 3Box associated with the given address

Kind: static method ofBox
Returns:Box - the 3Box instance for the given address

Check if the given address is logged in

Kind: static method ofBox
Returns:Boolean - true if the user is logged in

Instanciate ipfs used by 3Box without calling openBox.

Kind: static method ofBox
Returns:IPFS - the ipfs instance

Kind: global class

• BoxApi
  • .listSpaces(address, opts) ⇒Object
  • .getSpace(address, name, opts) ⇒Object
  • .getThread(space, name, firstModerator, members, opts) ⇒Array.<Object>
  • .getThreadByAddress(address, opts) ⇒Array.<Object>
  • .getConfig(address, opts) ⇒Array.<Object>
  • .getProfile(address, opts) ⇒Object
  • .getProfiles(address, opts) ⇒Object
  • .profileGraphQL(query, opts) ⇒Object
  • .getVerifiedAccounts(profile) ⇒Object

Get the names of all spaces a user has

Kind: static method ofBoxApi
Returns:Object - an array with all spaces as strings

Get the public data in a space of a given address with the given name

Kind: static method ofBoxApi
Returns:Object - a json object with the public space data

Get all posts that are made to a thread.

Kind: static method ofBoxApi
Returns:Array.<Object> - An array of posts

Get all posts that are made to a thread.

Kind: static method ofBoxApi
Returns:Array.<Object> - An array of posts

Get the configuration of a users 3Box

Kind: static method ofBoxApi
Returns:Array.<Object> - An array of posts

Get the public profile of a given address

Kind: static method ofBoxApi
Returns:Object - a json object with the profile for the given address

Get a list of public profiles for given addresses. This relies on 3Box profile API.

Kind: static method ofBoxApi
Returns:Object - a json object with each key an address and value the profile

GraphQL for 3Box profile API

Kind: static method ofBoxApi
Returns:Object - a json object with each key an address and value the profile

Verifies the proofs of social accounts that is present in the profile.

Kind: static method ofBoxApi
Returns:Object - An object containing the accounts that have been verified

Kind: global class

• KeyValueStore
  • new KeyValueStore()
  • .get(key, opts) ⇒String |Object
  • .getMetadata(key) ⇒Metadata
  • .set(key, value) ⇒Boolean
  • .setMultiple(keys, values) ⇒Boolean
  • .remove(key) ⇒Boolean
  • .all(opts) ⇒Array.<(String|{value: String, timestamp: Number})>
  • .log() ⇒Array.<Object>

Please usebox.public orbox.private to get the instance of this class

Get the value and optionally metadata of the given key

Kind: instance method ofKeyValueStore
Returns:String |Object - the value associated with the key, undefined if there's no such key

Get metadata for for a given key

Kind: instance method ofKeyValueStore
Returns:Metadata - Metadata for the key, undefined if there's no such key

Set a value for the given key

Kind: instance method ofKeyValueStore
Returns:Boolean - true if successful

Set multiple values for multiple keys

Kind: instance method ofKeyValueStore
Returns:Boolean - true if successful, throw error if not

Remove the value for the given key

Kind: instance method ofKeyValueStore
Returns:Boolean - true if successful

Get all values and optionally metadata

Kind: instance method ofKeyValueStore
Returns:Array.<(String|{value: String, timestamp: Number})> - the values

Returns array of underlying log entries. In linearized order according to their Lamport clocks.Useful for generating a complete history of all operations on store.

Kind: instance method ofKeyValueStore
Returns:Array.<Object> - Array of ordered log entry objects
Example

constlog=store.logconstentry=log[0]console.log(entry)// { op: 'PUT', key: 'Name', value: 'Botbot', timeStamp: '1538575416068' }

Class representing a user.

Kind: global class

• User
  • .DID
  • .signClaim(payload, opts) ⇒String
  • .encrypt(message, opts, to) ⇒Object
  • .decrypt(encryptedObject) ⇒String

Kind: instance property ofUser
Properties

Sign a JWT claim

Kind: instance method ofUser
Returns:String - The signed JWT

Encrypt a message. By default encrypts messages symmetricallywith the users private key. If theto parameter is used,the message will be asymmetrically encrypted to the recipient.

Kind: instance method ofUser
Returns:Object - An object containing the encrypted payload

Decrypts a message if the user owns the correct key to decrypt it.

Kind: instance method ofUser
Returns:String - The clear text message

Kind: global class

• Space
  • new Space()
  • .public
  • .private
  • .syncDone
  • .user
  • .joinThread(name, opts) ⇒Thread
  • .createConfidentialThread(name) ⇒Thread
  • .joinThreadByAddress(address, opts) ⇒Thread
  • .subscribeThread(address, config)
  • .unsubscribeThread(address)
  • .subscribedThreads() ⇒Array.<Objects>

Please usebox.openSpace to get the instance of this class

Kind: instance property ofSpace
Properties

Kind: instance property ofSpace
Properties

Kind: instance property ofSpace
Properties

Kind: instance property ofSpace
Properties

Join a thread. Use this to start receiving updates from, and to post in threads

Kind: instance method ofSpace
Returns:Thread - An instance of the thread class for the joined thread

Create a confidential thread

Kind: instance method ofSpace
Returns:Thread - An instance of the thread class for the created thread

Join a thread by full thread address. Use this to start receiving updates from, and to post in threads

Kind: instance method ofSpace
Returns:Thread - An instance of the thread class for the joined thread

Subscribe to the given thread, if not already subscribed

Kind: instance method ofSpace

Unsubscribe from the given thread, if subscribed

Kind: instance method ofSpace

Get a list of all the threads subscribed to in this space

Kind: instance method ofSpace
Returns:Array.<Objects> - A list of thread objects as { address, firstModerator, members, name}

Kind: global class

• Thread
  • new Thread()
  • .post(message) ⇒String
  • .addModerator(id)
  • .listModerators() ⇒Array.<String>
  • .addMember(id)
  • .listMembers() ⇒Array.<String>
  • .deletePost(id)
  • .getPosts(opts) ⇒Array.<Object>
  • .onUpdate(updateFn)
  • .onNewCapabilities(updateFn)

Please usespace.joinThread to get the instance of this class

Post a message to the thread

Kind: instance method ofThread
Returns:String - The postId of the new post

Add a moderator to this thread, throws error is user can not add a moderator

Kind: instance method ofThread

List moderators

Kind: instance method ofThread
Returns:Array.<String> - Array of moderator DIDs

Add a member to this thread, throws if user can not add member, throw is not member thread

Kind: instance method ofThread

List members, throws if not member thread

Kind: instance method ofThread
Returns:Array.<String> - Array of member DIDs

Delete post

Kind: instance method ofThread

Returns an array of posts, based on the options.If hash not found when passing gt, gte, lt, or lte,the iterator will return all items (respecting limit and reverse).

Kind: instance method ofThread
Returns:Array.<Object> - true if successful

Register a function to be called after new updateshave been received from the network or locally.

Kind: instance method ofThread

Register a function to be called for every newcapability that is added to the thread access controller.This inlcudes when a moderator or member is added.The function takes one parameter, which is the capabilities obj, oryou can call listModerator / listMembers again instead.

Kind: instance method ofThread

Kind: global class

• Verified
  • new Verified()
  • .DID() ⇒String
  • .github() ⇒Object
  • .addGithub(gistUrl) ⇒Object
  • .twitter() ⇒Object
  • .addTwitter(claim) ⇒Object
  • .email() ⇒Object
  • .addEmail(claim) ⇒Object

Please usebox.verified to get the instance of this class

Returns the verified DID of the user

Kind: instance method ofVerified
Returns:String - The DID of the user

Verifies that the user has a valid github accountThrows an error otherwise.

Kind: instance method ofVerified
Returns:Object - Object containing username, and proof

Adds a github verification to the users profileThrows an error if the verification fails.

Kind: instance method ofVerified
Returns:Object - Object containing username, and proof

Verifies that the user has a valid twitter accountThrows an error otherwise.

Kind: instance method ofVerified
Returns:Object - Object containing username, proof, and the verifier

Adds a twitter verification to the users profileThrows an error if the verification fails.

Kind: instance method ofVerified
Returns:Object - Object containing username, proof, and the verifier

Verifies that the user has a verified email accountThrows an error otherwise.

Kind: instance method ofVerified
Returns:Object - Object containing username, proof, and the verifier

Adds an email verification to the users profileThrows an error if the verification fails.

Kind: instance method ofVerified
Returns:Object - Object containing username, proof, and the verifier