@sepior/sdk v0.20.6

Sepior node-sdk

This is the Sepior node SDK. This can be used on Node as well as in the browser with browserify.

The package contains a SepiorServicesClient witch can be used for communicating with the Sepior key servers.

Building the SDK

Make sure you have node installed (version 6 or later). Then do

npm install

To build a standalone version of the sdk do

gulp build-standalone

The file dist/bundle.js can then be included directly using a script tag on a html page, i.e., like this:

<script src="bundle.js"></script>

The SDK can be accessed as the global variable SepiorSDK

Authentication

The SDK supports some authentication methods, but can easily be used with a custom strategy (implementing AuthenticationClient).

Username/Password Authentication

Below is an example of initializing the SepiorServicesClient with username/password authentication.

In the example we also provide an optional storage object. If the example is run in the browser we simply use the sessionStorage. If run in node on a server, we use a custom NodeStorage object that stores bearer tokens in RAM. Providing a storage object when initializing the SDK is highly recommended for better performance, since it lets the SDK perform many calls without having to login to the key servers every time.

const _storage = {}
class NodeStorage {
    getItem (k) {
        return _storage[k]
    }
    setItem (k, v) {
        _storage[k] = v
    }
}
const storage = typeof window === 'undefined' ? new NodeStorage() : window.sessionStorage
const {SepiorServicesClient} = require('@sepior/sdk')
const client = SepiorServicesClient.createPasswordBasedClient(
    ['ks1.example.com', 'ks2.example.com', 'ks3.example.com'],
    'application_id', {username, password, storage})

...

Custom Authentication

Implementing a custom authentication strategy can be done as below.

const {SepiorServicesClient, AuthenticationClient} = require('@sepior/sdk')
class StubAuthenticationClient extends AuthenticationClient {
    constructor () {
        super()
        this.tokens = {
            'https://ks1.example.com': 't1',
            'https://ks2.example.com': 't2',
            'https://ks3.example.com': 't3'
        }
    }

    authenticate(host) {
        return this.tokens[host]
    }
}

const client = new SepiorServicesClient(
    ['https://ks1.example.com', 'https://ks2.example.com', 'https://ks3.example.com'],
    'application_id',
    new StubAuthentcationClient())

...

Encryption/Decryption

Encrypting and decrypting is preferably done using streams.

Following is an example of, given a client: SepiorServicesClient and fileUid: string, reading a file, foo.txt, encrypting it, and saving it as foo.txt.sep.

const fs = require('fs')
const inStream = fs.createReadStream('./foo.txt')
const outStream = fs.createWriteStream('./foo.txt.sep')
const encryptStream = client.basis.fetchEncryptionStream(fileUid)

inStream.pipe(encryptStream).pipe(outStream)

Decryption is very similar

const fs = require('fs')
const inStream = fs.createReadStream('./foo.txt.sep')
const outStream = fs.createWriteStream('./foo.txt')
const decryptionStream = client.basis.fetchDecryptionStream()

inStream.pipe(decryptionStream).pipe(outStream)

You can also encrypt a buffer. Example of encrypting buffer: Buffer

...

client
    .basis.createResource()
    .then((resourceId) => client.basis.encryptBuffer(resourceId, buffer))
    .then((buffer) => {
        ...
    })

Example of decrypting buffer: Buffer

...

client
    .basis.decrypt(buffer)
    .then((buffer) => {
        ...
    })

Examples

See the /examples folder for more elaborate examples on how to use this SDK.

• Buffer example: Create a new user and encrypt a buffer.
• Sharing example: Shows how one user can share a resource with another user.

Tests

Remember to run the lint'er:

gulp lint

There are two types of tests: e2e- and unit-tests. The unit tests should be runnable on a local machine having Firefox and Google Chrome installed with no setup. The e2e tests requires a cluster to run. The cluster can either be a new one provisioned using Sepport or an existing cluster.

Provision new cluster using Sepport by running:

sepport login -u $SEPPORT_USER -t $SEPPORT_TOKEN
sepport start -n "name of cluster"
sepport create-user -u default_user0 -p user
sepport create-user -u default_user1 -p user

and then running gulp test-e2e-with-cluster for browser tests and node tests.

Use an existing cluster by setting the server addresses SDK_E2E_SERVERS=http(s)://<server-addr1>:port,http(s)://<server-addr2>:port,...,http(s)://<server-addrN>:port The cluster must have the application id 'test_application_id1' or use the APPLICATION_ID environment variable to specify an existing application id. Run gulp test-e2e for browser tests and gulp test-e2e-node for node tests.

Be aware that SDK_E2E_SERVERS will take precedence if you go back and forth between the two approaches.

All browser tests can also be run on BrowserStack by setting the environment variables: BROWSER_STACK_USERNAME and BROWSER_STACK_ACCESS_KEY.

The following environment variables will have default values corresponding to clusters created through Sepport. When testing against a local cluster use these default values: PRIMARY_ITERATION_COUNT=1 SECONDARY_ITERATION_COUNT=1 GROUP_ID=0

Contributing

When contributing changes remember to update the CHANGELOG.md.

Releasing

When releasing a new version (x.x.x) do the following:

• Update the change log by creating a new section (headed x.x.x) containing the content of the unreleased section
• Correct the package version in package.json
• Commit these changes with the message: chore: Release x.x.x Notice: This commit should only contain the changes to package.json and CHANGELOG.md
• Create branch, push commit, and merge to master.
• Make sure that all relevant pipelines are green. (If not, what then?)
• Pull master, make sure the commit made above is the latest in the log
• Tag this commit git tag -a x.x.x -m "Release x.x.x"
• Push tag git push --tags (don't push tags before the merge to master)