SNJS

SNJS is a client-side JavaScript library for Standard Notes that contains shared logic for all Standard Notes clients.

Note: This branch covers the 004 protocol, which is in development. To view the current production code, switch over to the master branch.

Introduction

SNJS (Standard Notes JavaScript) is a shared library we use in all Standard Notes clients (desktop, web, and mobile React Native). Its role is essentially to extract any business or data logic from client code, so that clients are mostly responsible for UI-level code, and don’t have to think about encryption and key stretching, or even authentication or storage specifics. Extracting the code into a shared library also prevents us from having to write the same critical code on multiple platforms.

The entry point of SNJS is the SNApplication class. The application class is a complete unit of application functionality. Theoretically, many instances of an application can be created, each with its own storage namespace and memory state. This can allow clients to support multiple user accounts.

An application must be supplied a custom subclass of DeviceInterface. This allows the library to generalize all behavior a client will need to perform throughout normal client operation, such as saving data to a local database store, saving key/values, and accessing the keychain.

The application interacts with a variety of services and managers to facilitate complete client functionality. While the distinction is not fully technical, a service can be thought of as a class that allows consumers to perform actions on demand, while a manager is responsible for managing and reacting to application state (but also expose on-demand functions). All managers and services live in lib/services.

SNJS interacts with sncrypto to perform operations as mentioned in the specification document. This includes operations like key generation and data encryption.

SNJS also interacts with a Standard Notes syncing-server, which is dumb data and sync store that deals with encrypted data, and never learns of client secrets or sensitive information.

Installation

npm install --save snjs

Integrating in module environment

import { SNApplication } from 'snjs';

Integrating in non-module web environment

<script src="snjs.js"></script>
Object.assign(window, SNLibrary);

Usage

1. Initialize an application:

const serverUrl = getServerURL();
const deviceInterface = new DeviceInterfaceSubclass();
const app = new SNApplication({
   deviceInterface: deviceInterface,
   environment: Environments.Web,
   platform: Platforms.MacWeb,
   host: serverUrl
});

2. Launch the application:

 await app.prepareForLaunch({
  receiveChallenge: (challenge, orchestrator) => {

  }
 });
 await application.launch();

Once the app is launched, you may perform any app-related functions, including:

Signing into an account

app.signIn({
  email, 
  password
}).then((response) => {

});

Registering a new account

app.register({
  email, 
  password
}).then((response) => {

});

Lock the app with a passcode

app.setPasscode(somePasscode).then(() => {

});

Create a note

const item = await app.createManagedItem({
  contentType: ContentTypes.Note, 
  content: {
    title: 'Ideas',
    text: 'Coming soon.'
  }
});
/** Save the item both locally and sync with server */
await app.saveItem({ item: item });

Stream notes

app.streamItems({
  contentType: ContentTypes.Note, 
  stream: ({ notes }) => {
    reloadUI(notes);
  }
});

Building

1. npm install
2. npm run start to start Webpack in development mode (watches changes), or npm run bundle to create dist files.

Tests

Tests must be run in the browser due to WebCrypto dependency.

1. node test-server.js
2. Open browser to http://localhost:9001/test/test.html.

Tests depend on a syncing-server instance running locally on port 3000 (branch 004 of the server repository as well). This port can be configured as necessary.

Note: Many tests involve registering for a new account as part of the beforeEach block for that test suite. Each account registration call takes close to 1 second, as key generation with Argon2 is tuned to take close to 1 second. However, this will depend on machine performance. If a test fails due to timeout being exceeded, please increase the timeout for that test. Note that the browser tab which runs the tests must remain in the foreground while the tests are running due to browsers de-optimizing inactive tabs.

Notes

• SNJS uses an asynchronous API. All functions are asynchronous, and return immediately even if they have not finished. Add .then() to every call to be notified of the result, or use await if you don't want to use callbacks.

Help

Join the #dev channel in our Slack group for help and discussion.