npm package: @seald-io/reversibility-tools
Description: Seald reversibility tools
Author: Seald SAS
Latest version: 0.1.0-7

# seald-reversibility-tools

A tool to use to fully decrypt all your data stored with the Seald SDK.

This uses the reversibility exports that Seald provides their customers upon request.

This is intended as a one-way tool to leave Seald.

This tool is a Node.JS library, intended to be used in `.js` scripts that a developper writes to do this process.

This process is done in 3 steps:
- Getting a database of decrypted identities
- Getting a database of decrypted session keys
- Decrypting the data itself

The full documentation can be found [here](https://docs.seald.io/sdk/guides/reversibility.html).

An example project using it is available [here](https://github.com/seald/seald-reversibility-tools-demo).


## Seald data export

To obtain this export, you must contact Seald support. You will need to provide a public key to encrypt the data.

To generate a pair of keys, you can use the following code example:

```javascript
import { node as sscrypto } from 'sscrypto'
import fs from 'node:fs'

const rsaKeyPair = await sscrypto.PrivateKey.generate(4096)

await fs.promises.writeFile('publicKey.key', rsaKeyPair.toB64({ publicOnly: true }), 'utf8')
await fs.promises.writeFile('privateKey.key', rsaKeyPair.toB64(), 'utf8')
```

Running this code creates two files:
- A 'publicKey.key' file, containing the encryption key that you must provide to us in order to export the data.
- A 'privateKey.key' file, containing the key that will be used to decrypt the exported data.


## Getting a database of decrypted identities

A database of decrypted identities (the output of this step) is a JSONLines file, containing:

```
{ sealdId: string, deviceId: string, identity: string }
```

The `identity` field here contains the Base64 encoding of the identity buffer.

This file can be constructed in multiple ways.

First, it can be done directly by the developer, by calling `sealdSdk.exportIdentity()` on their clients, then sending these identities back to their server, and constructing this file themselves.

Also, this database can be obtained by using the `decryptSsksExport(ssksExportPath, privateKey, outputPath, { appId, ssksTmrKeysPath, ssksStrictPasswordsPath })` function of the reversibility tools.

In this function call:
- `ssksExportPath` is the path to the export file for SSKS provided by Seald
- `privateKey` is an SSCrypto instance of your private key for which the exports were encrypted
- `outputPath` is the path to which to write the output file (the directory must already exist). If the file already exists, it will be overwritten.
- `appId` is your Seald App ID
- `ssksTmrKeysPath` is an optional argument, if you want to retrieve the identities from SSKS 2MR. It is the path to a file that is exported from your database, containing the `twoManRuleKey` or `rawTwoManRuleKey` for each user of your app, stored in a JSONLines file, in the following format:
```
{ userId: string, sealdId?: string, deviceId?: string, rawTwoManRuleKey?: string, twoManRuleKey?: string }
```
Each line must contain one, and only one, of `rawTwoManRuleKey` or `twoManRuleKey`.
The fields `sealdId` and `deviceId` are optional, and are used to check that the decrypted identity indeed corresponds to what is expected.
- `ssksStrictPasswordsPath` is an optional argument, if you want to retrieve the identities from SSKS Password. It is the path to a file that is exported from your database, containing the `password` or `rawEncryptionKey` for each user of your app, stored in a JSONLines file, in the following format:
```
{ userId: string, sealdId?: string, deviceId?: string, password?: string, rawEncryptionKey?: string }
```
Each line must contain one, and only one, of `password` or `rawEncryptionKey`.
The fields `sealdId` and `deviceId` are optional, and are used to check that the decrypted identity indeed corresponds to what is expected.


## Getting a database of decrypted session keys

Once you have the database of decrypted identities, you can use the `decryptApiExport(apiExportPath, decryptedIdentitiesPath, privateKey, outputPath, { tmrAccessesOverEncryptionKeysPath?, symEncKeysPath?, appId? })` function of the reversibility tools.

In this function call:
- `apiExportPath` is the path to the export file for the main Seald API provided by Seald
- `decryptedIdentitiesPath` is the path to the file that is the result of the previous step
- `privateKey` is an SSCrypto instance of your private key for which the exports were encrypted
- `tmrAccessesOverEncryptionKeysPath` is an optional argument, if you want to retrieve session keys from TMR Accesses. This should be the path to a file that is exported from your database, containing the `rawOverEncryptionKey` for each TMR Access, stored in a JSONLines file, in the following format:

```
{ sessionId: string, tmrAccessId: string, rawOverEncryptionKey: string }
```
- `groupTmrTemporaryKeysOverEncryptionKeysPath` is an optional argument, if you want to retrieve session keys from TMR temporary keys. This should be the path to a file that is exported from your database, containing the `rawOverEncryptionKey` for each TMR Temporary key, stored in a JSONLines file, in the following format:

```
{ gTMRTKId: string, rawOverEncryptionKey: string }
```

- `symEncKeysPath` is an optional argument, if you want to retrieve session keys from SymEncKeys. This should be the path to a file that is exported from your database, containing the Sym Enc Keys, stored in a JSONLines file, in the following format:

```
{ sessionId: string, symEncKeyId: string, rawSecret?: string, rawSymKey?: string, password?: string }
```

- `appId` is your Seald App ID. It is required only if you pass `symEncKeysPath`.

Each line must contain one, and only one, of `password` or the pair `rawSecret` and `rawSymKey`.

This will result in a JSONLines file in the following format:

```
{ sessionId: string, key: string }
```


## Decrypting the data itself

Once you have the database of decrypted session keys, you can use the `decryptMessage(encryptedMessage, decryptedSessionKeysPath, { raw , sessionId })` and `decryptFile(encryptedFileStream, decryptedSessionKeysPath, { sessionId })` functions to decrypt messages and files respectively.

In the `decryptMessage` function call:
- `encryptedMessage` is the encrypted message to decrypt
- `decryptedSessionKeysPath` is the path to the file that is the result of the previous step
- `raw` is an optional boolean that defaults to `false`, and that you shoud set to `true` if the message was encrypted as a raw message
- `sessionId` is the session ID to which this message corresponds. Optional if the message is not raw. Required if the message is raw.

This returns the content of the decrypted message as a `string`.

In the `decryptFile` function call:
- `encryptedFileStream` is a Readable stream of the file to decrypt
- `decryptedSessionKeysPath` is the path to the file that is the result of the previous step
- `sessionId` is the session ID to which this file corresponds. Optional.

This returns:
- `stream`, which is a `Readable` stream which contains the content of the decrypted file
- `promise`, which resolves as soon as the parsing is finished and which contains the file size `size` , the file name `filename`, the protocol version `protocol`, and the parsed session ID `mid`