Skip to content

Commit

Permalink
🔥 Refactor to remove TDF helper class (#249)
Browse files Browse the repository at this point in the history 
A functional refactor of tdf.ts

- Remove TDF helper class
- Since that eliminates the ability to mock out helper methods, disable where needed, and add additional functionality to test server where possible/doable.
  • Loading branch information
@dmihalcik-virtru
dmihalcik-virtru authored Oct 31, 2023
1 parent 0d72e65 commit 2208fbb
Show file tree
Hide file tree
Showing 24 changed files with 1,365 additions and 1,748 deletions.
58 changes: 58 additions & 0 deletions lib/package-lock.json
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 5 additions & 3 deletions lib/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,16 +44,17 @@
},
"scripts": {
"build": "npm run clean && tsc && tsc --project tsconfig.commonjs.json && ../scripts/add-module-types.sh",
"clean": "rm -rf {build,coverage,dist}",
"build:watch": "tsc --watch",
"clean": "rm -rf {build,coverage,dist,tests/mocha/dist}",
"coverage:merge": "for x in mocha wtr; do cp coverage/$x/coverage-final.json coverage/$x.json; done; nyc report --reporter text --reporter lcov -t coverage --lines 75 --statements 75 --branches 70 --functions 65 --check-coverage >coverage/coverage.txt",
"doc": "typedoc --out dist/docs src/index.ts",
"format": "prettier --write \"{src,tdf3,tests}/**/*.ts\"",
"license-check": "license-checker-rseidelsohn --production --onlyAllow 'Apache-2.0; BSD; CC-BY-4.0; ISC; MIT'",
"lint": "eslint ./src/**/*.ts ./tdf3/**/*.ts ./tests/**/*.ts",
"prepack": "npm run build",
"test": "npm run build && npm run test:mocha && npm run test:wtr && npm run test:browser && npm run coverage:merge",
"test:browser": "rm -rf tests/mocha/dist && node tests/server.cjs & npx webpack --config webpack.test.config.cjs && npx karma start karma.conf.cjs; node tests/stopServer.cjs",
"test:mocha": "node tests/server.cjs & trap \"node tests/stopServer.cjs\" EXIT; c8 --exclude=\"dist/web/tests/\" --exclude=\"dist/web/tdf3/src/utils/aws-lib-storage/\" --exclude=\"dist/web/tests/**/*\" --report-dir=./coverage/mocha mocha 'dist/web/tests/mocha/**/*.spec.js' --file tests/mocha/setup.js && npx c8 report --reporter=json --report-dir=./coverage/mocha",
"test:browser": "node dist/web/tests/server.js & trap \"node dist/web/tests/stopServer.js\" EXIT; npx webpack --config webpack.test.config.cjs && npx karma start karma.conf.cjs",
"test:mocha": "node dist/web/tests/server.js & trap \"node dist/web/tests/stopServer.js\" EXIT; c8 --exclude=\"dist/web/tests/\" --exclude=\"dist/web/tdf3/src/utils/aws-lib-storage/\" --exclude=\"dist/web/tests/**/*\" --report-dir=./coverage/mocha mocha 'dist/web/tests/mocha/**/*.spec.js' --file dist/web/tests/mocha/setup.js && npx c8 report --reporter=json --report-dir=./coverage/mocha",
"test:wtr": "web-test-runner",
"watch": "(trap 'kill 0' SIGINT; npm run build && (npm run build:watch & npm run test -- --watch))"
},
Expand All @@ -76,6 +77,7 @@
"@types/buffer-crc32": "^0.2.2",
"@types/chai": "~4.3.5",
"@types/jest": "^29.5.3",
"@types/jsdom": "^21.1.4",
"@types/jsonwebtoken": "~9.0.2",
"@types/mocha": "~10.0.1",
"@types/node": "^20.4.5",
Expand Down
265 changes: 2 additions & 263 deletions lib/tdf3/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ const { TDF3Client } = require("@opentdf/client");
console.log(`deciphered text :${plaintext}`);
})();
```

### browser
```js
const client = new Client.Client({
Expand All @@ -81,267 +82,5 @@ Rest is the same, you could use `withArrayBufferSource` for files in browser. Fo
a.download = "filenName.html";
a.href = "data:text/html;charset=utf-8," + encodeURIComponent(plainString);
```
clicking on that line allows you to download the file

## Methods

### create()

Creates a new instance of TDF.

```js
const tdfInstance = TDF.create();
```

### setProtocol(protocol)

Set the protocol to be used in either encryption or decryption steps.

```js
tdfInstance.setProtocol('zipstream');
```

#### protocol

Type: `String`

Currently only `'zip'` and `'zipstream'` are implemented. `'zipstream'` should be used when reading
from/writing to a stream.

### setPrivateKey(privateKey)

Sets the private key onto the TDF instance to be used in either the encryption or decryption steps.

```js
tdfInstance.setPrivateKey(privateKey);
```

#### privateKey

Type: `String`

The PEM-encoded private key as a string.

### setPublicKey(publicKey)

Sets the public key onto the TDF instance to be used in either the encryption or decryption steps.

```js
tdfInstance.setPublicKey(publicKey);
```

#### publicKey

Type: `String`

The PEM-encoded public key as a string.

### setEncryption(encryptionObject)

Set the encryption object onto the TDF instance.

```js
tdfInstance.setEncryption(encryptionObject);
```

#### encryptionObject.type

Type: `String`

The type of encryption, currently the only option is `split` to represent key splitting

#### encryptionObject.cipher

Type: `String`

The type of cipher to use for encryption. Available options are `'aes-256-gcm'` and `'aes-256-cbc'`.

### addKeyAccess(keyAccessObject)

Adds a [Key Access Object](https://developer.virtru.com/docs/keyaccessobject) to a TDF instance.

```js
await tdfInstance.addKeyAccess(keyAccessObject);
```

### setPolicy(policyObject)

Sets the [Policy Object](https://developer.virtru.com/docs/policy-object) on a TDF instance.

```js
tdfInstance.setPolicy(policyObject);
```

### setDefaultSegmentSize(segmentSize)

Sets the default size of each segment, in bytes, onto a TDF instance.

```js
tdfInstance.setDefaultSegmentSize(segmentSize);
```

#### segmentSize

Type: `Integer`

Default is set to `1024 * 1024` if one is not provided.

### setIntegrityAlgorithm(integrityAlgorithm, segmentIntegrityAlgorithm [optional])

Sets the integrity algorithm and segment integrity algorithms onto a TDF instance.

```js
tdfInstance.setIntegrityAlgorithm(integrityAlgorithm, segmentIntegrityAlgorithm);
```

#### integrityAlgorithm

Type: `String`

The type of algorithm used to create the root signature, found in the manifest
[integrityInformation](https://developer.virtru.com/docs/manifestjson#section-encryptioninformationintegrityinformation).
Available options are `hs256`.

#### segmentIntegrityAlgorithm

Type: `String`

The type of algorithm used to creat segment signatures. This parameter is optional, and if one is
not provided the `integrityAlgorithm` will be used. Available options are `gmac`.

### addContentStream(contentStream)

Sets a content stream on a TDF instance. Used during encryption when the library needs to read from
a content stream to encrypt stream chunks, eventually to be written as an encrypted file.

```js
tdfInstance.addContentStream(contentStream);
```

#### contentStream

The current implementation of the tdf3-js uses [Node streams](https://nodejs.org/api/stream.html).
For example, you can create a readStream that allows tdf3-js to read from a file source:

```js
const contentStream = fs.createReadStream(_my_file_loc, { encoding: 'binary' });
```

If you are working on a browser-only solution, tdf3-js offers a mock stream that provides a custom
in-memory stream that mimicks Node streams.

#### fileData

Type: `Byte`

The file's data, read from a file upload, for example:

```js
const reader = new FileReader();
reader.onload = (e) => {
const filedata = reader.result;
//do something with the filedata
};
```

This value can also be set to `null`, as would be the case for a writeStream (no data present upon
creation).

#### isEncryptOperation

Type: `Boolean`

A boolean that describes whether this stream is used for an encryption or decryption operation. This
is used by the mock stream in lieu of having separate streams (e.g., `createReadStream`,
`createWriteStream`)

### write()

Writes the encrypted content to memory, which can then be saved using any non-streaming method

```js
const result = await tdfInstance.write();

fs.writeFileSync(_my_filename_, result.binary.asBuffer(), { encoding: 'binary', flag: 'w' });
```

### writeStream(writeStream)

Writes the encrypted content to a write stream provided.

```js
await tdfInstance.writeStream(writeStream);
```

#### writeStream

Type: `Node stream`

The stream can be used to write to a file location, or in-memory.

### readStream(chunker, outputStream)

Reads the content given a `utils.chunker` object and writes to an `outputStream`, for example a
file.

#### url

Type: `String`

The URL of the remote resource from which tdf3-js will read data.

#### outputStream

Type: `Node stream`

The stream can be used to write to a file location, or in-memory.

### generatePolicyUuid()

Creates a unique identifier for a policy object. Returns a String.

```js
const uuid = await TDF.generatePolicyUuid();
```

### generateKeyPair()

Uses tdf3-js's built-in crypto services to generate a public and private key pair. Returns an object
with `privateKey` and `publicKey` properties.

```js
const keyPair = await TDF.generateKeyPair();
const privateKey = keyPair.privateKey;
const publicKey = keyPair.publicKey;
```

#### kasURL

Type: `String`

The URL of the KAS public key endpoint, for example: `http://localhost:4000/api/kas/kas_public_key`

#### loadTDFStream(url)

Loads a TDF stream by its remote url, placing the manifest JSON and encrypted payload in memory

```js
await tdfInstance.loadTDFStream(url);
```

#### loadTDF(tdfPath)

Loads a TDF file by its filename string

```js
await tdfInstance.loadTDF(tdfPath);
```

#### sync

Performs a 'syncing' of the symmetric wrapped key and Policy Object. For `remote` Key Access types,
this is performed automatically on encryption.

```js
await tdfInstance.sync();
```
clicking on that line allows you to download the file
Loading

0 comments on commit 2208fbb

Please sign in to comment.