Skip to main content

JavaScript client SDK v0.1.4

Installation

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

Run the following command in your terminal.

npm i -S @blindnet/sdk-javascript

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

nametyperequireddescription
tokenstringtrueAuthentication token generated by server SDK.
endpointstringfalseURL 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

nametyperequireddescription
tokenstringtrueAuthentication 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

nametyperequireddescription
secretstringtrueA 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

typedescription
AuthenticationErrorToken has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceErrorError on blindnet server.
PasswordErrorA 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

nametyperequireddescription
passwordstringtrueA 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

nametyperequireddescription
newSecretstringtrueA new secret used to encrypt user's keys.
oldSecretstringfalseCurrent 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

typedescription
AuthenticationErrorToken has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceErrorError on blindnet server.
PasswordErrorBad oldSecret is provided.
UserNotInitializedErrorA user is not logged into blindnet and oldSecret is not provided.
UserNotFoundErrorA 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

nametyperequireddescription
datastring | File | ArrayBuffer | Uint8ArraytrueData to encrypt. Multiple types are supported.
metadata{ [key: string]: any }falseMetadata 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

typedescription
AuthenticationErrorToken has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceErrorError on blindnet server.
BadFormatErrordata or metadata has a wrong type.
NotEncryptabeErrorThere 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

nametyperequireddescription
encryptedDataArrayBuffer | Uint8ArraytrueEncrypted 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

typedescription
AuthenticationErrorToken has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceErrorError on blindnet server.
UserNotInitializedErrorA user is not logged into blindnet.
NoAccessErrorA user has no access to encrypted data.
EncryptionErrorData could not be decrypted. Either due to wrong data format or the keys were deleted from blindnet.

Errors

typedescription
AuthenticationErrorToken has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceErrorError on blindnet server.
UserNotInitializedErrorA user is not logged into blindnet.
NoAccessErrorA user has no access to encrypted data.
EncryptionErrorData 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

nametyperequireddescription
userIdstringtrueId of a user to whom access is being given.

Return type

Promise<void>

The operation succeeded if an exception wasn't thrown.

Errors

typedescription
AuthenticationErrorToken has expired or is invalid. Generate a new token and call refreshToken.
BlindnetServiceErrorError on blindnet server.
UserNotFoundErrorA 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