A key feature of Radiks is support for private collaboration between multiple users. Supporting collaboration with client-side encryption and user-owned storage can be complicated but the patterns to implement it are generally the same among most applications. Radiks provides out-of-the box for collaboration, making it easy to build private, collaborative apps.
A key feature of Radiks is support for private collaboration between multiple users. Supporting collaboration with client-side encryption and user-owned storage can be complicated, but the patterns to implement it are generally the same among most applications. Radiks supplies interfaces for collaboration, making it easy to build private, collaborative apps.
You use the <ahref="https://github.com/blockstack/radiks/blob/master/src/models/user-group.ts"target="_blank"><code>UserGroup</code></a> class to build a collaborative group with Radiks. In this section, you learn about this class.
@ -29,7 +29,7 @@ The general workflow for creating a collaborative group that can share and edit
As they participate in a group, the group's members can create and update models that are related to the group. These models **must** contain a `userGroupId` attribute used to reference the group. This allows Radiks to know which keys to use for encryption and signing.
When needed, the group admin can remove a user from a group. To remove a user from the group, the admin creates a new private key for signing and encryption. Then, the admin updates the `GroupMembership` of all users _except_ the user they just removed. This is also known as rotating the key.
When needed, the group admin can remove a user from a group. To remove a user from the group, the admin creates a new private key for signing and encryption. Then, the admin updates the `GroupMembership` of all users _except_ the user they just removed. This update-and-remove action is also known as rotating the key.
After a key is rotated, all new and updated models must use the new key for signing. Radiks-server validates all group-related models to ensure that they're signed with the most up-to-date key.
@ -39,7 +39,7 @@ This section details the methods on the <a href="https://github.com/blockstack/r
### Create a UserGroup
To create a `UserGroup`, your application must import the class from `radiks`:
To create a `UserGroup`, you must import the class into your application from `radiks`:
Many applications server data that users create to share publicly with others, Facebook, Twitter, and Instagram are examples of such applications. Decentralized applications that want to create comparable multi-user experiences must ensure that anything a user creates for public sharing is likewise still under control the creator in the user's Gaia storage.
Many applications server data that users create to share publicly with others, Facebook, Twitter, and Instagram are examples of such applications. Decentralized applications that want to create comparable multi-user experiences must ensure that anything a user creates for public sharing is likewise still under control of the creator in the user's Gaia storage.
For example, if Twitter were a decentralized application where many different users creating their own tweets and those tweets are stored in each user's own Gaia storage. In such a situation, developer need a way to track of everyone's tweets, display tweets in user timelines, and perform searches across tweets. Radiks exists to support these kind of scenarios in that it allows applications to query across multiple user data, using complicated queries like text search, joins, and filters.
For example, if Twitter were a decentralized application where many different users creating their own tweets and those tweets are stored in each user's own Gaia storage. In such a situation,a developer needs a way to track of everyone's tweets, display tweets in user timelines, and perform searches across tweets. Radiks exists to support these kinds of scenarios in that it allows applications to query across multiple user data, using complicated queries like text search, joins, and filters.
Radiks allows applications to query data in a performant and flexible way. Each application that wishes to index and query in this way requires its own Radiks server.
## How Radiks works with application data
Radiks consists of a database, a pre-built server, and a client. Each application adds Radiks client library to their application. With this library a developer models their application data. The model defines an applications data schema for the Radiks server. Then, you can use calls to this model to write and query data that uses that schema. Whenever an application saves or updates data on behalf of a user, Radiks follows this process:
Radiks consists of a database, a pre-built server, and a client. Each application adds Radiks client library to their application. With this library a developer models their application data. The model defines an application data schema for the Radiks server. Then, you can use calls to this model to write and query data that use that schema. Whenever an application saves or updates data on behalf of a user, Radiks follows this flow:
1. Encrypts private user data on the client-side.
2. Saves a raw JSON of this encrypted data in the user's Gaia storage.
3. Stores the encrypted data on the Radiks server.
Radiks stores both public data and sensitive, non-private data. Radiks encrypts sensitive data by default before the data leaves the client. Your application can query Radiks for public data and then decrypt the sensitive information on the client. This means that the Radiks server is only able to return queries for unencrypted data.
Radiks stores public data and sensitive, non-private data. Radiks encrypts sensitive data by default before the data leaves the client. Your application can query Radiks for public data and then decrypt the sensitive information on the client. This means that the Radiks server is only able to return queries for unencrypted data.
## How Radiks authorizes writes
Radiks must ensure that user's own any data they are writing. To ensure this, Radiks creates and manages *signing keys*. These keys sign all writes that a user performs. Radiks-server validates all signatures before performing a write. This guarantees that a user is not able to over-write another user's data.
Radiks must ensure that user's own any data they are writing. To ensure this, Radiks creates and manages *signing keys*. These keys sign all writes that a user performs. Radiks-server validates all signatures before performing a write. This guarantees that a user is not able to overwrite another user's data.
Radiks-server also is built to support writes in a collaborative, but private, situation. For example, consider a collaborative document editing application, where users can create organizations and invite users to that organization. All users in that organization have read and write privileges to the organization data. These organizations have single shared key that is used to sign and encrypt data.
Radiks-server also is built to support writes in a collaborative but private situation. For example, consider a collaborative document editing application, where users can create organizations and invite users to that organization. All users in that organization have read and write privileges to the organization data. These organizations have a single shared key that is used to sign and encrypt data.
When an organization administrator needs to remove a user from the group, they'll revoke a previous key and create a new one. Radiks is aware of these relationships, and will only support writes that are signed with the current active key related to an organization.
When an organization administrator needs to remove a user from the group, they'll revoke a previous key and create a new one. Radiks is aware of these relationships, and will only support writes that are signed with the currently active key related to an organization.
## Is Radiks decentralized
@ -55,12 +55,12 @@ Although Radiks applications rely on a centrally-hosted database, an application
</tr>
<tr>
<td>Censorship resistance</td>
<td><p>All data is also stored in Gaia, no third-party can revoke access to this data.
<td><p>All data is also stored in Gaia; no third-party can revoke access to this data.
</p></td>
</tr>
<tr>
<td>Maximum privacy</td>
<td><p>All data is encrypted on the clientside before being stored anywhere using Blockstack authorization. The application host cannot inspect, sell, or use user data in any way that a user doesn't explicitly authorize.
<td><p>All data is encrypted on the client-side before being stored anywhere using Blockstack authorization. The application host cannot inspect, sell, or use user data in any way that a user doesn't explicitly authorize.
Radiks allows you to model your client data. You can then query this data and display it for user in multi-player applications. For example, a social application where users want to see the comments of other users. This page explains how to create a model in your distributed application using Radiks.
Radiks allows you to model your client data. You can then query this data and display it for a user in multi-player applications. A social application where users want to see the comments of other users is an example of a multi-player application. This page explains how to create a model in your distributed application using Radiks.
* TOC
{:toc}
@ -71,13 +71,13 @@ The `key` in this object is the field name and the value, for example, `String
To define options, pass an object, with a mandatory `type` field. The only supported option right now is `decrypted`. This defaults to `false`, meaning the field is encrypted before the data is stored publicly. If you specify `true`, then the field is not encrypted.
Storing unencrypted fields is useful if you want to be able to query the field when fetching data. A good use-case for storing decrypted fields is to store a `foreignId` that references a different model, for a "belongs-to" type of relation.
Storing unencrypted fields is useful if you want to be able to query the field when fetching data. A good use-case for storing decrypted fields is to store a `foreignId` that references a different model, for a "belongs-to" type of relationship.
**Never add the `decrypted` option to fields that contain sensitive user data.** Blockstack data is stored in a decentralized Gaia storage and anyone can read the user's data. That's why encrypting it is so important. If you want to filter sensitive data, then you should do it on the client-side, after decrypting it.
### Include defaults
You may want to include an optional `defaults` static property for some field values. For example in the class below the `likesDogs` field is a `Boolean` and the default is `true`.
You may want to include an optional `defaults` static property for some field values. For example, in the class below, the `likesDogs` field is a `Boolean`, and the default is `true`.
```javascript
import { Model } from 'radiks';
@ -122,7 +122,7 @@ class MyAppUserModel extends User {
}
```
The default `User` model defines a `username` but you can add a `displayName` to allow the user to define a name unique in your app.
The default `User` model defines a `username`, but you can add a `displayName` to allow the user to set unique name in your app.
## Use a model you have defined
@ -130,7 +130,7 @@ In this section, you learn how to use a model you have defined.
### About the _id attribute
All model instances have an `_id` attribute. An `_id` is used as a primary key when storing data, and is used for fetching a model. Radiks also creates a `createdAt` and `updatedAt` property when creating and saving models.
All model instances have an `_id` attribute. An `_id` is used as a primary key when storing data and is used for fetching a model. Radiks also creates a `createdAt` and `updatedAt` property when creating and saving models.
If, when constructing a model's instance, you don't pass an `_id`, Radiks creates an `_id` for you automatically. This automatically created id uses the [`uuid/v4`](https://github.com/kelektiv/node-uuid) format. This automatic `_id` is returned by the constructor.
@ -183,7 +183,7 @@ Important, calling `update` does **not** save the instance.
### Save changes
To save an instance to Gaia and MongoDB, call the `save()` method which returns a promise. This method encrypts all attributes that do not have the `decrypted` option in their schema. Then, it saves a JSON representation of the model in Gaia, as well as in the MongoDB.
To save an instance to Gaia and MongoDB, call the `save()` method, which returns a promise. This method encrypts all attributes that do not have the `decrypted` option in their schema. Then, it saves a JSON representation of the model in Gaia, as well as in the MongoDB.
@ -16,19 +16,19 @@ Radiks-server is a `node.js` application that uses [MongoDB](https://www.mongodb
### Install and configure MongoDB
In the future, Radiks-server will support various different databases, but right now only MongoDB 3.6 or higher is supported. MongoDB 3.6 and higher contains fixes required for naming patterns in keys.
In the future, Radiks-server will support various different databases, but right now, only MongoDB 3.6 or higher is supported. MongoDB 3.6 and higher contains fixes required for naming patterns in keys.
{% include note.html content="The steps assumes you want to install and run the MongoDB software locally on your workstation for testing and development. If you are deploying for a production application, you would install MongoDB on your application server or on a server connected to it. " %}
{% include note.html content="The steps assume you want to install and run the MongoDB software locally on your workstation for testing and development. If you are deploying for a production application, you will install MongoDB on your application server or on a server connected to it. " %}
1. <ahref="https://docs.mongodb.com/manual/administration/install-community/"target="_blank">Download and install MongoDB 3.6 or higher</a> on your workstation.
You can also install MongoDB using your favorite package manager, for example, Homebrew is recommended for macOS. If you are testing on a local workstation, you can use a `docker` image instead of installing locally.
You can also install MongoDB using your favorite package manager; for example, Homebrew is recommended for macOS. If you are testing on a local workstation, you can use a `docker` image instead of installing locally.
2. Start the MongoDB service and verify it is running.
3. On your MongoDB instance, create a database for your application data.
You can use the <ahref="https://docs.mongodb.com/manual/mongo/"target="_blank">Mongo shell</a> to do this or you can <ahref="https://www.mongodb.com/download-center/compass"target="_blank">install the MongoDB Compass</a> software to explore and work with MongoDB data.
You can use the <ahref="https://docs.mongodb.com/manual/mongo/"target="_blank">Mongo shell</a> to do this, or you can <ahref="https://www.mongodb.com/download-center/compass"target="_blank">install the MongoDB Compass</a> software to explore and work with MongoDB data.
4. Create a username/password combination with `root` privileges on your new database.
@ -47,21 +47,21 @@ The easiest way to run `radiks-server` is to use the pre-packaged `node.js` serv
```bash
yarn global add radiks-server
```
The default port for Mongodb is `27017`, your instance may be configured differently. By default, Radiks-server will use `'MongoDB://localhost:27017/radiks-server'` as the `MongoDB_URI` value. This is suitable for local testing, but in production, you'll want to change the hostname and possible the database name.
The default port for Mongodb is `27017`; your instance may be configured differently. By default, Radiks-server will use `'MongoDB://localhost:27017/radiks-server'` as the `MongoDB_URI` value. This is suitable for local testing, but in production, you'll want to change the hostname and possibly the database name.
3. Start the `radiks-server` in the command line to confirm your installation.
```
$ radiks-server
(node:37750) DeprecationWarning: current Server Discovery and Monitoring engine is deprecated, and will be removed in a future version. To use the new Server Discover and Monitoring engine, pass option { useUnifiedTopology: true } to the MongoClient constructor.
(node:37750) DeprecationWarning: current Server Discovery and Monitoring engine is deprecated and will be removed in a future version. To use the new Server Discover and Monitoring engine, pass option { useUnifiedTopology: true } to the MongoClient constructor.
radiks-server is ready on http://localhost:1260
```
The `radiks-server` defaults to running on port `1260`. To change the default port, specify the `PORT` environment variable in your environment.
4. By default the server is running at `http://localhost:1260`
4. By default, the server is running at `http://localhost:1260`
4. Stop the `radiks` server process after you confirm it runs and your installation was a success.
4. Stop the `radiks` server process after you confirm it runs, and your installation was a success.
## Task 2. Set up your application
@ -72,7 +72,7 @@ You must set up your application to use Radiks. This requires installing the `ra
If you are using `blockstack.js` version 18 or earlier, you must use the Radiks version 0.1.\*, otherwise if you're using `blockstack.js` version 19 or higher, use Radiks 0.2.\* .
1. Change directory to the root of you application code.
2. Install the install the `radiks` client package.
2. Install the `radiks` client package.
<tableclass="uk-table uk-table-small">
<thead>
@ -141,9 +141,9 @@ If you are using `blockstack.js` version 18 or earlier, you must use the Radiks
## Task 3. Add startup code and build your application
To set up radiks.js, you only need to configure the URL that your Radiks-server instance is running on. If you're using the pre-built Radiks server, this will be `http://localhost:1260`. If you're in production or are using a custom Radiks server, you'll need to specify exactly which URL it's available at.
To set up radiks.js, you only need to configure the URL that your Radiks-server instance is running on. If you're using the pre-built Radiks server, this will be `http://localhost:1260`. If you're in production or are using a custom Radiks server, you'll need to specify the exact URL where it's available.
Radiks also is compatible with version 19 of blockstack.js, which requires you to configure a `UserSession` object to handle all user-data-related methods. You'll need to define this and pass it to your Radiks configuration, so that Radiks can know how to fetch information about the current logged in user.
Radiks also is compatible with version 19 of blockstack.js, which requires you to configure a `UserSession` object to handle all user-data-related methods. You'll need to define this and pass it to your Radiks configuration so that Radiks can know how to fetch information about the current logged in user.
### Configure your application to use your `radiks-server`.
Mary Anthony
5 years ago