dexie-encrypted - npm Package Compare versions

Comparing version 2.0.0-beta.1 to 2.0.0-beta.2

dist/index.d.ts

@@ -7,3 +7,3 @@ import Dexie from 'dexie';
 export declare const UNENCRYPTED_LIST: "UNENCRYPTED_LIST";
-export { clearAllTables, clearEncryptedTables } from './encryptDatabase';
-export declare function encryptDatabase<T extends Dexie>(db: T, encryptionKey: Uint8Array | Promise<Uint8Array>, tableSettings: CryptoSettings<T>, onKeyChange: (db: T) => Promise<any>, _nonceOverrideForTesting?: Uint8Array): void;
+export { clearAllTables, clearEncryptedTables } from './applyMiddleware';
+export declare function applyEncryptionMiddleware<T extends Dexie>(db: T, encryptionKey: Uint8Array | Promise<Uint8Array>, tableSettings: CryptoSettings<T>, onKeyChange: (db: T) => Promise<any>, _nonceOverrideForTesting?: Uint8Array): void;

dist/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.encryptDatabase = exports.UNENCRYPTED_LIST = exports.ENCRYPT_LIST = exports.NON_INDEXED_FIELDS = void 0;
-const encryptDatabase_1 = require("./encryptDatabase");
+exports.applyEncryptionMiddleware = exports.UNENCRYPTED_LIST = exports.ENCRYPT_LIST = exports.NON_INDEXED_FIELDS = void 0;
+const applyMiddleware_1 = require("./applyMiddleware");
 const encryptionMethods_1 = require("./encryptionMethods");
@@ -12,7 +12,7 @@ const types_1 = require("./types");
 exports.UNENCRYPTED_LIST = types_1.cryptoOptions.UNENCRYPTED_LIST;
-var encryptDatabase_2 = require("./encryptDatabase");
-Object.defineProperty(exports, "clearAllTables", { enumerable: true, get: function () { return encryptDatabase_2.clearAllTables; } });
-Object.defineProperty(exports, "clearEncryptedTables", { enumerable: true, get: function () { return encryptDatabase_2.clearEncryptedTables; } });
-function encryptDatabase(db, encryptionKey, tableSettings, onKeyChange, _nonceOverrideForTesting) {
-    encryptDatabase_1.encryptDatabaseWithCustomEncryption({
+var applyMiddleware_2 = require("./applyMiddleware");
+Object.defineProperty(exports, "clearAllTables", { enumerable: true, get: function () { return applyMiddleware_2.clearAllTables; } });
+Object.defineProperty(exports, "clearEncryptedTables", { enumerable: true, get: function () { return applyMiddleware_2.clearEncryptedTables; } });
+function applyEncryptionMiddleware(db, encryptionKey, tableSettings, onKeyChange, _nonceOverrideForTesting) {
+    applyMiddleware_1.applyMiddlewareWithCustomEncryption({
         db,
@@ -27,3 +27,3 @@ encryptionKey,
 }
-exports.encryptDatabase = encryptDatabase;
+exports.applyEncryptionMiddleware = applyEncryptionMiddleware;
 //# sourceMappingURL=index.js.map

package.json

 {
     "name": "dexie-encrypted",
-    "version": "2.0.0-beta.1",
+    "version": "2.0.0-beta.2",
     "description": "Encryption middleware for Dexie",
@@ -5,0 +5,0 @@ "main": "dist",

README.md

 # Dexie-encrypted
 
-This lets you transparently encrypt an IndexedDB database using [Dexie.js](https://dexie.org/) and [tweetnacl.js](https://tweetnacl.js.org).
+This lets you transparently encrypt an IndexedDB database using [Dexie.js](https://dexie.org/). By default it uses [tweetnacl.js](https://tweetnacl.js.org), but you may use any encryption method you desire. Note that Dexie-encrypted cannot encrypt indices as doing this would make the database unsearchable.
 
 ## Basic Usage
 
-Create a Dexie database and call `encrypt` on it with your encryption key in a Uint8Array.
+Create a Dexie database and call `applyEncryptionMiddleware` on it with your encryption key and encryption config.
 
@@ -13,3 +13,3 @@ _Note: dexie-encrypted creates a database table to hold its configuration so you must also bump your database version._
 import Dexie from 'dexie';
-import encrypt from 'dexie-encrypted';
+import { applyEncryptionMiddleware } from 'dexie-encrypted';
 
@@ -19,3 +19,3 @@ const db = new Dexie('MyDatabase');
 // set the key and provide a configuration of how to encrypt at a table level.
-encrypt(db, symmetricKey, {
+applyEncryptionMiddleware(db, symmetricKey, {
     friends: encrypt.NON_INDEXED_FIELDS,
@@ -46,3 +46,3 @@ });
 ```javascript
-encrypt(db, key, config, onKeyChange);
+applyEncryptionMiddleware(db, key, config, onKeyChange);
 ```
@@ -62,6 +62,8 @@
 
-Dexie-encrypted can be configured to encrypt all the data of a table, to select fields that are senesitvie or non-sensitive.
+### Table Level Config
 
+Dexie-encrypted will only encrypt tables you choose. It can be configured to encrypt all the data of a table, or you may select fields to encrypt or leave unencrypted. Fields can be any data type that can be added to IndexedDB, but must be top level fields.
+
 -   `encrypt.NON_INDEXED_FIELDS` - all data other than indices will be encrypted.
--   `encrypt.UNENCRYPTED_LIST` - all data other than indices and whitelisted fields will be encrypted.
+-   `encrypt.UNENCRYPTED_LIST` - all data other than indices and listed fields will be encrypted.
 -   `encrypt.ENCRYPT_LIST` - listed fields will be encrypted.
@@ -83,5 +85,32 @@
 
+### Using custom encryption methods
+
+The default will encrypt with tweetnacl, which at the time of publishing was the fastest method available, even faster than native WebCrypto. However, you may choose to use your own encryption methods. [The main file](./src/index.ts) of the repo contains a good example of this.
+
+```javascript
+import { applyMiddlewareWithCustomEncryption } from 'dexie-encrypted/dist/applyMiddleware';
+import { myCustomEncryptionMethod, myCustomDecryptionMethod } from './myEncryption';
+
+applyMiddlewareWithCustomEncryption({
+    db,
+    encryptionKey,
+    tableSettings,
+    encrypt: myCustomEncryptionMethod, // <--- right here
+    decrypt: myCustomDecryptionMethod, // <--- and here
+    onKeyChange,
+});
+```
+
+Note that this method takes a config object rather than several arguments.
+
+#### Custom Encryption Methods
+
+_see [the defaults](./src/encryptionMethods.ts) for an example_
+
+-   `customEncryptionMethod(key: Uint8Array, object: any)` - This method receives an object containing only the fields that must be encrypted. It's up to you to serialize it, encrypt it, and return the encrypted data. It expects a Uint8Array to be returned from encryption.
+-   `customDecryptionMethod(key: Uint8Array, encryptedData: Uint8Array)` Thismethod receives the data as it was returned from the encryption method. It must decrypt and deserialize it into an object. The returned value will be spread on to a new object with the unencrypted data.
+
 ## Keys - Do not store your key locally without encryption.
 
-Creating and persisting the key is not a part of this library. To generate a key, tweetnacl provides a method to generate a random array, you can do what it's doing under the hood and [use webcrypto directly](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues), but most likely you should have a back end generate a key and send it to you. Take a look at the documentation for [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) and [TextEncoder](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)/[TextDecoder](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) to figure out the best method for you.
+Creating and persisting the key is not a part of this library. The best way to handle this is to have the back end generate a key for you, keeping it unique per user or per session. You may use some other user-provided data, such as a password, to generate the encryption key, but do not store it in LocalStorage or a cookie, as this would allow anyone with access to the computer to derive the key and decrypt the database.
 
@@ -100,3 +129,3 @@ ### Strategies for storing keys
 
-Dexie-encrypted saves your configuration to a database table, if you change your encryption configuration it will automatically reencrypt the database the next time it's open.
+Dexie-encrypted saves your configuration to a database table, if you change your encryption configuration it will run the `onKeyChanged` callback. In this callback you can clear the existing tables and provide new data, or do whatever you choose.
 
@@ -103,0 +132,0 @@ ## Notes

No alert changes

Improved metrics

Total package byte prevSize

52265

increased by22.88%

Number of package files

27

increased by12.5%

Lines of code

560

increased by22.81%

Number of lines in readme file

132

increased by28.16%

No dependency changes