ironcorelabs / ironnode Goto Github PK

View Code? Open in Web Editor NEW

11.0 8.0 3.0 1 MB

IronCore Labs SDK for NodeJS Applications

Home Page: https://ironcorelabs.com/docs

License: GNU Affero General Public License v3.0

JavaScript 1.25% TypeScript 98.65% Nix 0.10%

cryptography proxy-re-encryption transform-encryption nodejs

ironnode's Introduction

IronCore Labs NodeJS SDK

SDK for using IronCore Labs from your NodeJS server side applications. Read our documentation for further information about how to integrate this library into your server side application. Also check out the integration directory for an example of consuming this library.

Supported Platforms

	Node 16	Node 18	Node 20
Linux x64 glibc	✓	✓	✓
Linux x64 musl-libc	✓	✓	✓
Linux arm64 glibc	✓	✓	✓
Linux arm64 musl-libc	✓	✓	✓
OSX x64	✓	✓	✓
OSX arm64	✓	✓	✓
Windows x64	✓	✓	✓

Installation

npm install @ironcorelabs/ironnode

This SDK relies on our recrypt-node-binding Node addon library. This library is distributed as a binary which is specific to both an architecture (OSX/Linux/Windows) and Node version (10/12). When you NPM install this SDK it will automatically determine the proper binary to pull down into your node_modules directory based on your architecture and Node version.

This means that you'll need to make sure that the machine that runs npm install to install this library is the architecture/Node version where the code will run. This library will not work if you run npm install on an OSX machine and move the node_modules directory over to a Linux machine, for example.

If the machine you run npm install on is not one of the supported architectures you will get an install failure. If there's an architecture or Node version that you'd like supported that isn't yet available, open a new issue and we'll look into adding support for it.

Types

This library contains a TypeScript definitions file which shows the available classes and methods for this SDK.

Local Development

Integration Testing

In order to run the integration tests for this repo you need to have an IronCore Project, Segment, and Service Key to use. If you haven't yet, sign up for an account and create a set of those to use for testing this library.

Once you have all three items configured, do the following:

Copy your Service Key private.key file into the integration directory.
Create a project.json file in the integration directory with the following JSON form

{
    "projectId": numeric project ID,
    "segmentId": string segment ID,
    "serviceKeyId": numeric service key ID,
}

Once you have your Service Key private key and config file setup, you can run the yarn start command to kick off an interactive CLI tool. This tool will first let you pick a user operation, either verify, create, or generate device keys. You can verify existing users or create new users from this menu. Before any SDK operations are allowed to run you must generate local device keys. When you pick this option and the keys are generated, they will be stored in a .device.json file in the integration directory. Subsequent CLI runs will ask if you want to use those local device keys.

Unit Testing and Linting

This repo uses NPM scripts in order to run all tests and linting. You can run both the unit tests and linting together by running yarn test.

Linting

TSLint is used to run linting on all source code. In addition this repo has a Prettier configuration to auto-format source code upon save. Prettier should be configured within your IDE before contributing to this project.

yarn run lint

Unit Testing

This repo uses Jest for all unit testing.

yarn run unit

To run a subset of the tests you can use the -t option of Jest to only run tests whose name matches the provided value

yarn run unit -t group

ironnode's People

Contributors

Stargazers

Watchers

ironnode's Issues

Support ability to lookup user public keys

One nice features to add is the ability to lookup users public keys by ID. This allows users to lookup to see if another user has setup their IronCore keys yet or not. Likely expose this as a SDK.user.getPublicKey method or similar.

Expose created and updated timestamps for all document and group objects

Expose fields from API now that they are provided for all document and group operations.

Restrict character set on document and group create

Add method to let user change their master private key escrow password

SDK.user.changePasscode(oldPasscode, newPasscode)

Update to support node 18

Once IronCoreLabs/recrypt-node-binding#107 merges update this library to support node 18 and release.

Add apple silicon (arm64) support?

Looks like arm64 is not a supported platform, would it be possible to add support for Apple silicon?
The readme says to open an issue to potentially get support added.
Would this be possible?

Here's an image for context:

Please let me know if there's some more you need from me.
Thanks

Add device list (with signing key) to the User SDK

Consume https://github.com/IronCoreLabs/ironcore-id/pull/853. ironweb will have this functionality before anything else, see it to try to have a consistent API.

Add method to let users retrieve public keys from a list of users given their IDs

This would provide a nice way to determine if another user in the system has created their keys yet or not. Likely exposed as SDK.user.getPublicKey or similar.

Detect Cloudflare rate limiting error and return with specific error code

When someone hits our rate limit within Cloudflare, we should respond with a specific error code telling the user that they're being rate limited. Then consumers of the SDK can decision of this. When we hit the CF ratelimit they'll return us an HTTP error code of 429 which we should use to decision off of.

Upgrade handlebars, js-yaml

Known high severity security vulnerability detected in handlebars < 4.0.14 defined in yarn.lock.

yarn.lock update suggested: handlebars ~> 4.0.14.

Known high severity security vulnerability detected in js-yaml < 3.13.1 defined in yarn.lock.

yarn.lock update suggested: js-yaml ~> 3.13.1.

Expose group update and delete methods

group.update(options)

Options will be an object where currently the only supported field is name: string | null.

group.delete(groupID)

Delete the provided group given it's ID.

Implement standard device key format

We are going to standardize the DeviceContext/DeviceKeys JSON format across all SDKs. The proposed format (in Typescript) is:

{
    deviceId: number;
    accountId: string;
    segmentId: number;
    devicePrivateKey: Base64String;
    // “expanded private key” (both pub/priv)
    signingPrivateKey: Base64String; 
}

see: IronCoreLabs/ironoxide#25

Migrate CI from Travis to GitHub

Consume latest node-binding and add windows support

Once the neon binding native module works for Windows, change the package.json file to add support for Windows. Then test on Windows to make sure it works as advertised.

Add document create option to not encrypt document to author

Add a new boolean flag (default true) on document.create which controls whether the author of the document will have the document be encrypted to them. The document.create call must share with at least one user/group, so if this option is false, the grantList must have at least one entry.

Also need to consume changes to how the document list, document get response structures can change if the author is requesting a document that they cannot decrypt.

URL escape user IDs when performing user list operation

Allow device name to be provided as part of `IronNode.generateDeviceKeys()` call

Now that the API takes a device name as part of the device add call, we should let callers of the SDK provide a name for their device which will be useful for the response of the device list API call.

generateDeviceKeys(jwt: string, password: string, {options: {deviceName: string}})

Add methods for user and group private key rotation

Should be implemented in the same form as IronWeb.

Replace usage of `Recrypt.deriveSymmetricKey` with `Recrypt.hash256`

We currently use the Recrypt.deriveSymmetricKey within IronNode to get a private key from a plaintext. While this works, it makes the code look weird so instead we should use the new Recrypt.hash256 method which is more generic.

Consume new device APIs

Expose a SDK.device.list() method
Expose a SDK.device.delete() method

Implement support for v2 document header

Add code to support version 2 of our document header which embeds the document ID and internal segment ID to the front of the document. The implementation will be as follows:

Byte 1: Version number, set to 2.
Byte 2,3: Encoded number which represents the size of the following header bytes, N
Bytes 4-N+3: utf-8 encoded JSON header which contains document ID (_did_) and internal segment ID (_sid_). fields
Bytes N+4-End: Encrypted document which includes AES IV and encrypted data.

Since we need to know what the document ID is at the time we do the encryption, we can also no longer rely on ironcore-id to generate document IDs for us if the caller doesn't provide one. So in addition to this we'll also generate the random document IDs on the client before we pass them to the server.

When we get a document that is version 1, we'll continue to do what we do today and just pull off the first byte. No changes will be made to the SDK to remove the need for providing a document ID as part of the various operations.