JavaScript client SDK v0.1.4

Installation

Pick one of the following methods to install the blindnet devkit.

npm

Run the following command in your terminal.

npm i -S @blindnet/sdk-javascript

yarn

Run the following command in your terminal.

yarn add @blindnet/sdk-javascript

umd

Download the umd file and include it in your HTML file.
File can be downloaded here.

<script src="blindnet.umd.js"></script>

Imports

If the SDK was installed as an npm package, it is imported as

import { Blindnet, util, error } from '@blindnet/sdk-javascript'

If it was imported as an umd package, use

const { Blindnet, util, error } = blindnet

The api is encapsulated in the Blindnet class.

Initialization

blindnet devkit must be initialized before you can use it (with the exception of some static methods, e.g. secret derivation method).

Initialization is done with the init method.

static function init(token: string, endpoint?: string): Blindnet

Parameters

name	type	required	description
token	string	true	Authentication token generated by server SDK.
endpoint	string	false	URL of the blindnet server. Default value is https://api.blindnet.io. For testing, use https://test.blindnet.io.

Return type

Blindnet (An instance which you use to call SDK methods.)

const blindnet = Blindnet.init(token)
blindnet.connect(secret)

Refreshing the session

After the token expires, AuthenticationError will be thrown on api calls. Generate a new token using server SDK and call refreshToken.

function refreshToken(token: string): void

Parameters

name	type	required	description
token	string	true	Authentication token generated by server SDK.

Return type

void

Logging-in

A user must be logged-into to blindnet before using any Blindnet api methods (with the of some static methods or when encrypting). The user both registers and later authenticates in blindnet with the method connect.

function connect(secret: string): Promise<void>

Parameters

name	type	required	description
secret	string	true	A secret value used to encrypt and decrypt user's keys. Usually, should be derived from user's password using the deriveSecrets method.

Return type

Promise<void>

The operation succeeded if an exception wasn't thrown.

Errors

type	description
AuthenticationError	Token has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceError	Error on blindnet server.
PasswordError	A bad secret has been provided. Could not decrypt the user's keys.

Deriving secrets

User's password is a sensitive data. As it can be used both to log-into your application and to encrypt user's keys in blindnet, it should be split into two parts and each part should be used for different purposes.

function deriveSecrets(
    password: string
): Promise<{ blindnetSecret: string, appSecret: string }>

Parameters

name	type	required	description
password	string	true	A value generated by a user. It can be the user's password or e.g. answer to a security question.

Return type

Promise<{ blindnetSecret: string, appSecret: string }>

If a user's log-in password is used as an input parameter, use blindnetSecret in the connect method and appSecret to log-into your application.

Logging-out

After the user is logged out of your app, following method should be called to clean the user's keys from the browser

Blindnet.disconnect()

Changing login secret

If an app password is used to log-in users into blindnet, make sure to call this method after a user changes the password. Remember to call deriveSecrets.

function changeSecret(newSecret: string, oldSecret?: string): Promise<void>

Parameters

name	type	required	description
newSecret	string	true	A new secret used to encrypt user's keys.
oldSecret	string	false	Current secret used to encrypt user's keys. If the user is currently not logged into blindnet, oldSecret should be provided into the method changeSecret.

Return type

Promise<void>

The operation succeeded if an exception wasn't thrown.

Errors

type	description
AuthenticationError	Token has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceError	Error on blindnet server.
PasswordError	Bad oldSecret is provided.
UserNotInitializedError	A user is not logged into blindnet and oldSecret is not provided.
UserNotFoundError	A user was not registered or was deleted from blindnet.

Encrypting

function encrypt(
    data: string | File | ArrayBuffer | Uint8Array,
    metadata?: { [key: string]: any }
): Promise<{ dataId: string, encryptedData: ArrayBuffer }>

Parameters

name	type	required	description
data	string | File | ArrayBuffer | Uint8Array	true	Data to encrypt. Multiple types are supported.
metadata	{ [key: string]: any }	false	Metadata in JSON format.

Return type

Promise<{ dataId: string, encryptedData: ArrayBuffer }>

dataId can be used to delete a data keys using the Server SDK.
encryptedData can be encoded using toBase64 and toHex methods.

Errors

type	description
AuthenticationError	Token has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceError	Error on blindnet server.
BadFormatError	data or metadata has a wrong type.
NotEncryptabeError	There are no users to encrypt the data to.

Decrypting

function decrypt(
    encryptedData: ArrayBuffer | Uint8Array
): Promise<{
    data: string | File | Bytes,
    metadata: { dataType: DataType, [key: string]: any; }}>

Parameters

name	type	required	description
encryptedData	ArrayBuffer | Uint8Array	true	Encrypted data to decrypt (the result of the encrypt method). If it was encoded, it can be decoded using fromBase64 or fromHex.

Return type

Promise<{
    data: string | File | ArrayBuffer | Uint8Array,
    metadata: { dataType: DataType, [key: string]: any; }}>

type DataType =
    | { type: 'STRING' }
    | { type: 'FILE', name: string }
    | { type: 'BYTES' }

data is in format it was originally provided to the encrypt method. If not known, it can be inspected from the dataType property of the metadata.

Errors

type	description
AuthenticationError	Token has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceError	Error on blindnet server.
UserNotInitializedError	A user is not logged into blindnet.
NoAccessError	A user has no access to encrypted data.
EncryptionError	Data could not be decrypted. Either due to wrong data format or the keys were deleted from blindnet.

Errors

type	description
AuthenticationError	Token has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceError	Error on blindnet server.
UserNotInitializedError	A user is not logged into blindnet.
NoAccessError	A user has no access to encrypted data.
EncryptionError	Data could not be decrypted. Either due to wrong data format or the keys were deleted from blindnet.

Giving access to a user

A user can give access to all the encrypted data (to which the user already has access to) to another user.

function giveAccess(userId: string): Promise<void>

Parameters

name	type	required	description
userId	string	true	Id of a user to whom access is being given.

Return type

Promise<void>

The operation succeeded if an exception wasn't thrown.

Errors

type	description
AuthenticationError	Token has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceError	Error on blindnet server.
UserNotFoundError	A user whose id was provided as a parameter was not registered or was deleted from blindnet.

Helper methods

blindnet devkit provides the methods to encode and decode encrypted data, so it can be easily transferred and stored.

Helper methods can be imported as

import { util } from '@blindnet/sdk-javascript'
const { toBase64, fromBase64, toHex, fromHex } = util

Encoding

Encrypted data (result of the encrypt method) can be encoded using the following methods:

Encode to base64 string

function toBase64(encryptedData: ArrayBuffer): string

Encode to hexadecimal string

function toHex(encryptedData: ArrayBuffer): string

Decoding

A base64 or hex encoded string can be decoded into ArrayBuffer (and then passed to the decrypt method) using the following methods:

Decode from base64 string

function fromBase64(encoded: string): ArrayBuffer

Decode from hexadecimal string

function fromHex(encoded: string): ArrayBuffer