mongodb-client-encryption - npm Package Compare versions

Comparing version 0.3.1 to 1.0.0-rc0

index.js

 'use strict';
 
-module.exports = function(mongodb) {
+let defaultModule;
+function loadDefaultModule() {
+  if (!defaultModule) {
+    defaultModule = extension(require('mongodb'));
+  }
+
+  return defaultModule;
+}
+
+const MongoCryptError = require('./lib/common').MongoCryptError;
+function extension(mongodb) {
   const modules = { mongodb };
@@ -13,4 +23,21 @@
     ClientEncryption: modules.clientEncryption.ClientEncryption,
-    MongoCryptError: require('./lib/common').MongoCryptError
+    MongoCryptError
   };
+}
+
+module.exports = {
+  extension,
+  MongoCryptError,
+  get AutoEncrypter() {
+    const m = loadDefaultModule();
+    delete module.exports.AutoEncrypter;
+    module.exports.AutoEncrypter = m.AutoEncrypter;
+    return m.AutoEncrypter;
+  },
+  get ClientEncryption() {
+    const m = loadDefaultModule();
+    delete module.exports.ClientEncryption;
+    module.exports.ClientEncryption = m.ClientEncryption;
+    return m.ClientEncryption;
+  }
 };

lib/autoEncrypter.js

@@ -13,11 +13,48 @@ 'use strict';
   /**
-   * @typedef AutoEncrypter~AutoEncryptionExtraOptions
-   * @prop {string} [mongocryptdURI] overrides the uri used to connect to mongocryptd
-   * @prop {boolean} [mongocryptdBypassSpawn=false] if true, autoEncryption will not spawn a mongocryptd
-   * @prop {string} [mongocryptdSpawnPath] the path to the mongocryptd executable
-   * @prop {string[]} [mongocryptdSpawnArgs] command line arguments to pass to the mongocryptd executable
+   * Configuration options for a automatic client encryption.
+   *
+   * @typedef {Object} AutoEncrypter~AutoEncryptionOptions
+   * @property {MongoClient} [keyVaultClient] A `MongoClient` used to fetch keys from a key vault
+   * @property {string} [keyVaultNamespace] The namespace where keys are stored in the key vault
+   * @property {KMSProviders} [kmsProviders] Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.
+   * @property {object} [schemaMap] A map of namespaces to a local JSON schema for encryption
+   * @property {boolean} [bypassAutoEncryption] Allows the user to bypass auto encryption, maintaining implicit decryption
+   * @property {AutoEncrypter~logger} [options.logger] An optional hook to catch logging messages from the underlying encryption engine
+   * @property {AutoEncrypter~AutoEncryptionExtraOptions} [extraOptions] Extra options related to the mongocryptd process
    */
 
   /**
-   * An internal class to be used by the driver for auto encryption
+   * Extra options related to the mongocryptd process
+   * @typedef {object} AutoEncrypter~AutoEncryptionExtraOptions
+   * @property {string} [mongocryptdURI] A local process the driver communicates with to determine how to encrypt values in a command. Defaults to "mongodb://%2Fvar%2Fmongocryptd.sock" if domain sockets are available or "mongodb://localhost:27020" otherwise
+   * @property {boolean} [mongocryptdBypassSpawn=false] If true, autoEncryption will not attempt to spawn a mongocryptd before connecting
+   * @property {string} [mongocryptdSpawnPath] The path to the mongocryptd executable on the system
+   * @property {string[]} [mongocryptdSpawnArgs] Command line arguments to use when auto-spawning a mongocryptd
+   */
+
+  /**
+   * @callback AutoEncrypter~logger
+   * @description A callback that is invoked with logging information from
+   * the underlying C++ Bindings.
+   * @param {AutoEncrypter~logLevel} level The level of logging.
+   * @param {string} message The message to log
+   */
+
+  /**
+   * @name AutoEncrypter~logLevel
+   * @enum {number}
+   * @description
+   * The level of severity of the log message
+   *
+   * | Value | Level |
+   * |-------|-------|
+   * | 0 | Fatal Error |
+   * | 1 | Error |
+   * | 2 | Warning |
+   * | 3 | Info |
+   * | 4 | Trace |
+   */
+
+  /**
+   * @classdesc An internal class to be used by the driver for auto encryption
    * **NOTE**: Not meant to be instantiated directly, this is for internal use only.
@@ -27,24 +64,2 @@ */
     /**
-     * @name AutoEncrypter~logLevel
-     * @kind enum
-     * @description
-     * The level of severity of the log message
-     *
-     * | Value | Level |
-     * |-------|-------|
-     * | 0 | Fatal Error |
-     * | 1 | Error |
-     * | 2 | Warning |
-     * | 3 | Info |
-     * | 4 | Trace |
-     */
-    /**
-     * @callback AutoEncrypter~logger
-     * @descritpion A callback that is invoked with logging information from
-     * the underlying C++ Bindings.
-     * @param {AutoEncrypter~logLevel} level The level of logging. Valid values are 0 (Fatal Error), 1 (Error), 2 (Warning), 3 (Info), 4 (Trace)
-     * @param {string} message The message to log
-     */
-
-    /**
      * Create an AutoEncrypter
@@ -58,10 +73,4 @@ *
      * Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.
-     *
      * @param {MongoClient} client The client autoEncryption is enabled on
-     * @param {object} [options] Optional settings
-     * @param {string} [options.keyVaultNamespace='admin.dataKeys'] The namespace of the key vault, used to store encryption keys
-     * @param {object} [options.schemaMap] A local specification of a JSON schema used for encryption
-     * @param {KMSProviders} [options.kmsProviders] options for specific KMS providers to use
-     * @param {function} [options.logger] An optional hook to catch logging messages from the underlying encryption engine
-     * @param {AutoEncrypter~AutoEncryptionExtraOptions} [options.extraOptions] Extra options related to mongocryptd
+     * @param {AutoEncrypter~AutoEncryptionOptions} [options] Optional settings
      *
@@ -91,5 +100,7 @@ * @example
         useNewUrlParser: true,
-        useUnifiedTopology: true
+        useUnifiedTopology: true,
+        serverSelectionTimeoutMS: 1000
       });
       this._keyVaultNamespace = options.keyVaultNamespace || 'admin.datakeys';
+      this._keyVaultClient = options.keyVaultClient || client;
 
@@ -146,3 +157,3 @@ const mongoCryptOptions = {};
      */
-    encrypt(ns, cmd, callback) {
+    encrypt(ns, cmd, options, callback) {
       if (typeof ns !== 'string') {
@@ -156,4 +167,9 @@ throw new TypeError('Parameter `ns` must be a string');
 
+      if (typeof options === 'function' && callback == null) {
+        callback = options;
+        options = {};
+      }
+
       const bson = this._bson;
-      const commandBuffer = Buffer.isBuffer(cmd) ? cmd : bson.serialize(cmd);
+      const commandBuffer = Buffer.isBuffer(cmd) ? cmd : bson.serialize(cmd, options);
 
@@ -173,3 +189,3 @@ let context;
 
-      const stateMachine = new StateMachine();
+      const stateMachine = new StateMachine(options);
       stateMachine.execute(this, context, callback);
@@ -185,5 +201,10 @@ }
      */
-    decrypt(response, callback) {
+    decrypt(response, options, callback) {
+      if (typeof options === 'function' && callback == null) {
+        callback = options;
+        options = {};
+      }
+
       const bson = this._bson;
-      const buffer = Buffer.isBuffer(response) ? response : bson.serialize(response);
+      const buffer = Buffer.isBuffer(response) ? response : bson.serialize(response, options);
 
@@ -201,3 +222,3 @@ let context;
 
-      const stateMachine = new StateMachine();
+      const stateMachine = new StateMachine(options);
       stateMachine.execute(this, context, callback);
@@ -204,0 +225,0 @@ }

lib/clientEncryption.js

@@ -50,9 +50,9 @@ 'use strict';
   /**
-   * @typedef KMSProviders
+   * @typedef {object} KMSProviders
    * @description Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.
    * @prop {object} [aws] Configuration options for using 'aws' as your KMS provider
-   * @prop {string} [aws.accessKeyId] An AWS Access Key
-   * @prop {string} [aws.secretAccessKey] An AWS Secret Key
+   * @prop {string} [aws.accessKeyId] The access key used for the AWS KMS provider
+   * @prop {string} [aws.secretAccessKey] The secret access key used for the AWS KMS provider
    * @prop {object} [local] Configuration options for using 'local' as your KMS provider
-   * @prop {Buffer} [local.key] A 96-byte long Buffer used for local encryption
+   * @prop {Buffer} [local.key] The master key used to encrypt/decrypt data keys. A 96-byte long Buffer.
    */
@@ -70,2 +70,3 @@
      * @param {string} options.keyVaultNamespace The namespace of the key vault, used to store encryption keys
+     * @param {MongoClient} [options.keyVaultClient] A `MongoClient` used to fetch keys from a key vault. Defaults to `client`
      * @param {KMSProviders} [options.kmsProviders] options for specific KMS providers to use
@@ -104,2 +105,3 @@ *
       this._keyVaultNamespace = options.keyVaultNamespace;
+      this._keyVaultClient = options.keyVaultClient || client;
       this._mongoCrypt = new mc.MongoCrypt(options);
@@ -109,4 +111,6 @@ }
     /**
-     * @typedef ClientEncryption~dataKey
-     * @description A key used for manual encryption / decryption. Is a BSON Binary object.
+     * @typedef {Binary} ClientEncryption~dataKeyId
+     * @description The id of an existing dataKey. Is a bson Binary value.
+     * Can be used for {@link ClientEncryption.encrypt}, and can be used to directly
+     * query for the data key itself against the key vault namespace.
      */
@@ -117,7 +121,7 @@
      * @param {Error} [error] If present, indicates an error that occurred in the creation of the data key
-     * @param {ClientEncryption~dataKey} [dataKey] If present, returns the new data key
+     * @param {ClientEncryption~dataKeyId} [dataKeyId] If present, returns the id of the created data key
      */
 
     /**
-     * Creates a data key used for explicit encryption
+     * Creates a data key used for explicit encryption and inserts it into the key vault namespace
      *
@@ -129,5 +133,6 @@ * @param {string} provider The KMS provider used for this data key. Must be `'aws'` or `'local'`
      * @param {string} [options.masterKey.key] The Amazon Resource Name (ARN) to the AWS customer master key (CMK)
+     * @param {string} [options.masterKey.endpoint] An alternate host to send KMS requests to. May include port number.
      * @param {string[]} [options.keyAltNames] An optional list of string alternate names used to reference a key. If a key is created with alternate names, then encryption may refer to the key by the unique alternate name instead of by _id.
      * @param {ClientEncryption~createDataKeyCallback} [callback] Optional callback to invoke when key is created
-     * @returns {Promise|void} If no callback is provided, returns a Promise that either resolves with the created data key, or rejects with an error. If a callback is provided, returns nothing.
+     * @returns {Promise|void} If no callback is provided, returns a Promise that either resolves with {@link ClientEncryption~dataKeyId the id of the created data key}, or rejects with an error. If a callback is provided, returns nothing.
      * @example
@@ -145,7 +150,7 @@ * // Using callbacks to create a local key
      * // Using async/await to create a local key
-     * const dataKey = await clientEncryption.createDataKey('local');
+     * const dataKeyId = await clientEncryption.createDataKey('local');
      *
      * @example
      * // Using async/await to create an aws key
-     * const dataKey = await clientEncryption.createDataKey('aws', {
+     * const dataKeyId = await clientEncryption.createDataKey('aws', {
      *   masterKey: {
@@ -159,3 +164,3 @@ *     region: 'us-east-1',
      * // Using async/await to create an aws key with a keyAltName
-     * const dataKey = await clientEncryption.createDataKey('aws', {
+     * const dataKeyId = await clientEncryption.createDataKey('aws', {
      *   masterKey: {
@@ -185,6 +190,6 @@ *     region: 'us-east-1',
 
-          this._client
+          this._keyVaultClient
             .db(dbName)
             .collection(collectionName)
-            .insertOne(dataKey, (err, result) => {
+            .insertOne(dataKey, { w: 'majority' }, (err, result) => {
               if (err) {
@@ -208,9 +213,9 @@ cb(err, null);
     /**
-     * Explicitly encrypt a provided value. Note that either `options.dataKey` or `options.keyAltName` must
-     * be specified. Specifying both `options.dataKey` and `options.keyAltName` is considered an error.
+     * Explicitly encrypt a provided value. Note that either `options.keyId` or `options.keyAltName` must
+     * be specified. Specifying both `options.keyId` and `options.keyAltName` is considered an error.
      *
      * @param {*} value The value that you wish to serialize. Must be of a type that can be serialized into BSON
      * @param {object} options
-     * @param {ClientEncryption~dataKey} [options.dataKey] The Binary dataKey to use for encryption
-     * @param {string} [options.keyAltName] A unique string name corresponding to an already existing {{@link ClientEncryption~dataKey dataKey}}
+     * @param {ClientEncryption~dataKeyId} [options.keyId] The id of the Binary dataKey to use for encryption
+     * @param {string} [options.keyAltName] A unique string name corresponding to an already existing dataKey.
      * @param {} options.algorithm The algorithm to use for encryption. Must be either `'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic'` or `AEAD_AES_256_CBC_HMAC_SHA_512-Random'`
@@ -223,7 +228,7 @@ * @param {ClientEncryption~encryptCallback} [callback] Optional callback to invoke when value is encrypted
      * function encryptMyData(value, callback) {
-     *   clientEncryption.createDataKey('local', (err, dataKey) => {
+     *   clientEncryption.createDataKey('local', (err, keyId) => {
      *     if (err) {
      *       return callback(err);
      *     }
-     *     clientEncryption.encrypt(value, { dataKey, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' }, callback);
+     *     clientEncryption.encrypt(value, { keyId, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' }, callback);
      *   });
@@ -235,4 +240,4 @@ * }
      * async function encryptMyData(value) {
-     *   const dataKey = await clientEncryption.createDataKey('local');
-     *   return clientEncryption.encrypt(value, { dataKey, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' });
+     *   const keyId = await clientEncryption.createDataKey('local');
+     *   return clientEncryption.encrypt(value, { keyId, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' });
      * }
@@ -239,0 +244,0 @@ *

lib/mongocryptdManager.js

 'use strict';
 
 const spawn = require('child_process').spawn;
-const readFile = require('fs').readFile;
 
-const mongocryptdPidFileName = 'mongocryptd.pid';
-const checkIntervalMS = 50;
-
 /**
  * @ignore
- * A heuristic check to see if a mongocryptd is running. Checks for a mongocryptd.pid
- * file that contains valid JSON. If the pid file exists, the mongocryptd is likely
- * running.
- * @param {} callback Invoked with true if a valid pid file is found, false otherwise
- */
-function checkIsUp(callback) {
-  readFile(mongocryptdPidFileName, 'utf8', (err, data) => {
-    if (err) {
-      return callback(undefined, false);
-    }
-
-    if (!data || !data.length) {
-      return callback(undefined, false);
-    }
-
-    try {
-      JSON.parse(data);
-    } catch (e) {
-      return callback(e, false);
-    }
-
-    callback(undefined, true);
-  });
-}
-
-/**
- * @ignore
- * Attempts to wait for a mongocryptd to be up. Will check with checkIsUp
- * in 50ms intervals up to tries times.
- * @param {number} tries The number of times to check for a mongocryptd
- * @param {Function} callback Is called when either the number of tries have been
- * attempted, or when we think a mongocryptd is up
- */
-function waitForUp(tries, callback) {
-  if (tries <= 0) {
-    return callback();
-  }
-
-  checkIsUp((err, isUp) => {
-    if (isUp) {
-      return callback();
-    }
-
-    tries -= 1;
-    setTimeout(() => waitForUp(tries, callback), checkIntervalMS);
-  });
-}
-
-/**
- * @ignore
  * An internal class that handles spawning a mongocryptd.
@@ -87,6 +33,6 @@ */
     if (Array.isArray(extraOptions.mongocryptdSpawnArgs)) {
-      this.spawnArgs.concat(extraOptions.mongocryptdSpawnArgs);
+      this.spawnArgs = this.spawnArgs.concat(extraOptions.mongocryptdSpawnArgs);
     }
-    if (this.spawnArgs.indexOf('idleShutdownTimeoutSecs') < 0) {
-      this.spawnArgs.concat(['--idleShutdownTimeoutSecs', '60']);
+    if (this.spawnArgs.indexOf('--idleShutdownTimeoutSecs') < 0) {
+      this.spawnArgs.push('--idleShutdownTimeoutSecs', 60);
     }
@@ -102,24 +48,17 @@ }
   spawn(callback) {
-    checkIsUp((err, isUp) => {
-      if (!err && isUp) {
-        process.nextTick(callback);
-        return;
-      }
+    const cmdName = this.spawnPath || 'mongocryptd';
 
-      const cmdName = this.spawnPath || 'mongocryptd';
+    // Spawned with stdio: ignore and detatched:true
+    // to ensure child can outlive parent.
+    this._child = spawn(cmdName, this.spawnArgs, {
+      stdio: 'ignore',
+      detached: true
+    });
 
-      // Spawned with stdio: ignore and detatched:true
-      // to ensure child can outlive parent.
-      this._child = spawn(cmdName, this.spawnArgs, {
-        stdio: 'ignore',
-        detached: true
-      });
+    this._child.on('error', () => {});
 
-      this._child.on('error', () => {});
+    // unref child to remove handle from event loop
+    this._child.unref();
 
-      // unref child to remove handle from event loop
-      this._child.unref();
-
-      waitForUp(20, callback);
-    });
+    process.nextTick(callback);
   }
@@ -126,0 +65,0 @@ }

lib/stateMachine.js

@@ -71,2 +71,6 @@ 'use strict';
   class StateMachine {
+    constructor(options) {
+      this.options = options || {};
+    }
+
     /**
@@ -84,2 +88,3 @@ * @ignore
       const keyVaultNamespace = autoEncrypter._keyVaultNamespace;
+      const keyVaultClient = autoEncrypter._keyVaultClient;
       const mongocryptdClient = autoEncrypter._mongocryptdClient;
@@ -144,3 +149,3 @@ const mongocryptdManager = autoEncrypter._mongocryptdManager;
           const filter = context.nextMongoOperation();
-          this.fetchKeys(client, keyVaultNamespace, filter, (err, keys) => {
+          this.fetchKeys(keyVaultClient, keyVaultNamespace, filter, (err, keys) => {
             if (err) return callback(err, null);
@@ -189,3 +194,3 @@ keys.forEach(key => {
           }
-          callback(null, bson.deserialize(finalizedContext));
+          callback(null, bson.deserialize(finalizedContext, this.options));
           return;
@@ -215,3 +220,5 @@ }
     kmsRequest(request) {
-      const options = { host: request.endpoint, port: HTTPS_PORT };
+      const parsedUrl = request.endpoint.split(':');
+      const port = parsedUrl[1] != null ? Number.parseInt(parsedUrl[1], 10) : HTTPS_PORT;
+      const options = { host: parsedUrl[0], port };
       const message = request.message;
@@ -233,3 +240,5 @@
           socket.destroy();
-          reject(err);
+          const mcError = new MongoCryptError('KMS request failed');
+          mcError.originalError = err;
+          reject(mcError);
         });
@@ -290,3 +299,3 @@
       const dbName = databaseNamespace(ns);
-      const rawCommand = bson.deserialize(command);
+      const rawCommand = bson.deserialize(command, { promoteLongs: false, promoteValues: false });
 
@@ -299,3 +308,3 @@ client.db(dbName).command(rawCommand, (err, response) => {
 
-        callback(err, bson.serialize(response));
+        callback(err, bson.serialize(response, this.options));
       });
@@ -322,3 +331,3 @@ }
         .db(dbName)
-        .collection(collectionName)
+        .collection(collectionName, { readConcern: { level: 'majority' } })
         .find(filter)
@@ -325,0 +334,0 @@ .toArray((err, keys) => {

package.json

 {
   "name": "mongodb-client-encryption",
-  "version": "0.3.1",
+  "version": "1.0.0-rc0",
   "description": "Official client encryption module for the MongoDB Node.js driver",
@@ -9,2 +9,8 @@ "main": "index.js",
   },
+  "files": [
+    "lib",
+    "src",
+    "etc",
+    "binding.gyp"
+  ],
   "scripts": {
@@ -37,3 +43,3 @@ "install": "prebuild-install --tag-prefix node-v || node-gyp rebuild",
     "mocha": "^4.0.0",
-    "mongodb": "^3.2.7",
+    "mongodb": "^3.3.4-rc0",
     "mongodb-extjson": "^3.0.3",
@@ -47,2 +53,5 @@ "node-gyp": "^5.0.3",
   },
+  "peerDependencies": {
+    "mongodb": "~3.4.0"
+  },
   "repository": {
@@ -49,0 +58,0 @@ "url": "https://github.com/mongodb/libmongocrypt"

README.md

@@ -46,3 +46,3 @@ MongoDB Client Encryption
 <dl>
-<dt><a href="#KMSProviders">KMSProviders</a></dt>
+<dt><a href="#KMSProviders">KMSProviders</a> : <code>object</code></dt>
 <dd><p>Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.</p>
@@ -65,2 +65,4 @@ </dd>
 
+    * [~AutoEncryptionOptions](#AutoEncrypter..AutoEncryptionOptions)
+
     * [~AutoEncryptionExtraOptions](#AutoEncrypter..AutoEncryptionExtraOptions)
@@ -75,11 +77,6 @@
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| client | <code>MongoClient</code> |  | The client autoEncryption is enabled on |
-| [options] | <code>object</code> |  | Optional settings |
-| [options.keyVaultNamespace] | <code>string</code> | <code>&quot;&#x27;admin.dataKeys&#x27;&quot;</code> | The namespace of the key vault, used to store encryption keys |
-| [options.schemaMap] | <code>object</code> |  | A local specification of a JSON schema used for encryption |
-| [options.kmsProviders] | [<code>KMSProviders</code>](#KMSProviders) |  | options for specific KMS providers to use |
-| [options.logger] | <code>function</code> |  | An optional hook to catch logging messages from the underlying encryption engine |
-| [options.extraOptions] | [<code>AutoEncryptionExtraOptions</code>](#AutoEncrypter..AutoEncryptionExtraOptions) |  | Extra options related to mongocryptd |
+| Param | Type | Description |
+| --- | --- | --- |
+| client | <code>MongoClient</code> | The client autoEncryption is enabled on |
+| [options] | [<code>AutoEncryptionOptions</code>](#AutoEncrypter..AutoEncryptionOptions) | Optional settings |
 
@@ -126,2 +123,19 @@ Create an AutoEncrypter
 
+<a name="AutoEncrypter..AutoEncryptionOptions"></a>
+
+### *AutoEncrypter*~AutoEncryptionOptions
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| [keyVaultClient] | <code>MongoClient</code> | A `MongoClient` used to fetch keys from a key vault |
+| [keyVaultNamespace] | <code>string</code> | The namespace where keys are stored in the key vault |
+| [kmsProviders] | [<code>KMSProviders</code>](#KMSProviders) | Configuration options that are used by specific KMS providers during key generation, encryption, and decryption. |
+| [schemaMap] | <code>object</code> | A map of namespaces to a local JSON schema for encryption |
+| [bypassAutoEncryption] | <code>boolean</code> | Allows the user to bypass auto encryption, maintaining implicit decryption |
+| [options.logger] | [<code>logger</code>](#AutoEncrypter..logger) | An optional hook to catch logging messages from the underlying encryption engine |
+| [extraOptions] | [<code>AutoEncryptionExtraOptions</code>](#AutoEncrypter..AutoEncryptionExtraOptions) | Extra options related to the mongocryptd process |
+
+Configuration options for a automatic client encryption.
+
 <a name="AutoEncrypter..AutoEncryptionExtraOptions"></a>
@@ -134,18 +148,21 @@
 | --- | --- | --- | --- |
-| [mongocryptdURI] | <code>string</code> |  | overrides the uri used to connect to mongocryptd |
-| [mongocryptdBypassSpawn] | <code>boolean</code> | <code>false</code> | if true, autoEncryption will not spawn a mongocryptd |
-| [mongocryptdSpawnPath] | <code>string</code> |  | the path to the mongocryptd executable |
-| [mongocryptdSpawnArgs] | <code>Array.&lt;string&gt;</code> |  | command line arguments to pass to the mongocryptd executable |
+| [mongocryptURI] | <code>string</code> |  | A local process the driver communicates with to determine how to encrypt values in a command. Defaults to "mongodb://%2Fvar%2Fmongocryptd.sock" if domain sockets are available or "mongodb://localhost:27020" otherwise |
+| [mongocryptdBypassSpawn] | <code>boolean</code> | <code>false</code> | If true, autoEncryption will not attempt to spawn a mongocryptd before connecting |
+| [mongocryptdSpawnPath] | <code>string</code> |  | The path to the mongocryptd executable on the system |
+| [mongocryptdSpawnArgs] | <code>Array.&lt;string&gt;</code> |  | Command line arguments to use when auto-spawning a mongocryptd |
 
+Extra options related to the mongocryptd process
+
 <a name="AutoEncrypter..logger"></a>
 
 ### *AutoEncrypter*~logger
-**Descritpion**: A callback that is invoked with logging information from
-the underlying C++ Bindings.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| level | [<code>logLevel</code>](#AutoEncrypter..logLevel) | The level of logging. Valid values are 0 (Fatal Error), 1 (Error), 2 (Warning), 3 (Info), 4 (Trace) |
+| level | [<code>logLevel</code>](#AutoEncrypter..logLevel) | The level of logging. |
 | message | <code>string</code> | The message to log |
 
+A callback that is invoked with logging information from
+the underlying C++ Bindings.
+
 <a name="ClientEncryption"></a>
@@ -169,3 +186,3 @@
     * _inner_
-        * [~dataKey](#ClientEncryption..dataKey)
+        * [~dataKeyId](#ClientEncryption..dataKeyId)
 
@@ -226,8 +243,9 @@ * [~createDataKeyCallback](#ClientEncryption..createDataKeyCallback)
 | [options.masterKey.key] | <code>string</code> | The Amazon Resource Name (ARN) to the AWS customer master key (CMK) |
+| [options.masterKey.endpoint] | <code>string</code> | An alternate host to send KMS requests to. May include port number. |
 | [options.keyAltNames] | <code>Array.&lt;string&gt;</code> | An optional list of string alternate names used to reference a key. If a key is created with alternate names, then encryption may refer to the key by the unique alternate name instead of by _id. |
 | [callback] | [<code>createDataKeyCallback</code>](#ClientEncryption..createDataKeyCallback) | Optional callback to invoke when key is created |
 
-Creates a data key used for explicit encryption
+Creates a data key used for explicit encryption and inserts it into the key vault namespace
 
-**Returns**: <code>Promise</code> \| <code>void</code> - If no callback is provided, returns a Promise that either resolves with the created data key, or rejects with an error. If a callback is provided, returns nothing.  
+**Returns**: <code>Promise</code> \| <code>void</code> - If no callback is provided, returns a Promise that either resolves with [the id of the created data key](#ClientEncryption..dataKeyId), or rejects with an error. If a callback is provided, returns nothing.  
 **Example**  
@@ -247,3 +265,3 @@ ```js
 // Using async/await to create a local key
-const dataKey = await clientEncryption.createDataKey('local');
+const dataKeyId = await clientEncryption.createDataKey('local');
 ```
@@ -253,3 +271,3 @@ **Example**
 // Using async/await to create an aws key
-const dataKey = await clientEncryption.createDataKey('aws', {
+const dataKeyId = await clientEncryption.createDataKey('aws', {
   masterKey: {
@@ -264,3 +282,3 @@ region: 'us-east-1',
 // Using async/await to create an aws key with a keyAltName
-const dataKey = await clientEncryption.createDataKey('aws', {
+const dataKeyId = await clientEncryption.createDataKey('aws', {
   masterKey: {
@@ -281,9 +299,9 @@ region: 'us-east-1',
 | options | <code>object</code> |  |
-| [options.dataKey] | [<code>dataKey</code>](#ClientEncryption..dataKey) | The Binary dataKey to use for encryption |
-| [options.keyAltName] | <code>string</code> | A unique string name corresponding to an already existing {[dataKey](#ClientEncryption..dataKey)} |
+| [options.keyId] | [<code>dataKeyId</code>](#ClientEncryption..dataKeyId) | The id of the Binary dataKey to use for encryption |
+| [options.keyAltName] | <code>string</code> | A unique string name corresponding to an already existing dataKey. |
 | options.algorithm |  | The algorithm to use for encryption. Must be either `'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic'` or `AEAD_AES_256_CBC_HMAC_SHA_512-Random'` |
 | [callback] | [<code>encryptCallback</code>](#ClientEncryption..encryptCallback) | Optional callback to invoke when value is encrypted |
 
-Explicitly encrypt a provided value. Note that either `options.dataKey` or `options.keyAltName` must
-be specified. Specifying both `options.dataKey` and `options.keyAltName` is considered an error.
+Explicitly encrypt a provided value. Note that either `options.keyId` or `options.keyAltName` must
+be specified. Specifying both `options.keyId` and `options.keyAltName` is considered an error.
 
@@ -295,7 +313,7 @@ **Returns**: <code>Promise</code> \| <code>void</code> - If no callback is provided, returns a Promise that either resolves with the encrypted value, or rejects with an error. If a callback is provided, returns nothing.
 function encryptMyData(value, callback) {
-  clientEncryption.createDataKey('local', (err, dataKey) => {
+  clientEncryption.createDataKey('local', (err, keyId) => {
     if (err) {
       return callback(err);
     }
-    clientEncryption.encrypt(value, { dataKey, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' }, callback);
+    clientEncryption.encrypt(value, { keyId, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' }, callback);
   });
@@ -308,4 +326,4 @@ }
 async function encryptMyData(value) {
-  const dataKey = await clientEncryption.createDataKey('local');
-  return clientEncryption.encrypt(value, { dataKey, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' });
+  const keyId = await clientEncryption.createDataKey('local');
+  return clientEncryption.encrypt(value, { keyId, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' });
 }
@@ -347,6 +365,8 @@ ```
 ```
-<a name="ClientEncryption..dataKey"></a>
+<a name="ClientEncryption..dataKeyId"></a>
 
-### *ClientEncryption*~dataKey
-A key used for manual encryption / decryption. Is a BSON Binary object.
+### *ClientEncryption*~dataKeyId
+The id of an existing dataKey. Is a bson Binary value.
+Can be used for [ClientEncryption.encrypt](ClientEncryption.encrypt), and can be used to directly
+query for the data key itself against the key vault namespace.
 
@@ -360,3 +380,3 @@ <a name="ClientEncryption..createDataKeyCallback"></a>
 | [error] | <code>Error</code> | If present, indicates an error that occurred in the creation of the data key |
-| [dataKey] | [<code>dataKey</code>](#ClientEncryption..dataKey) | If present, returns the new data key |
+| [dataKeyId] | [<code>dataKeyId</code>](#ClientEncryption..dataKeyId) | If present, returns the id of the created data key |
 
@@ -394,8 +414,8 @@ <a name="ClientEncryption..encryptCallback"></a>
 | [aws] | <code>object</code> | Configuration options for using 'aws' as your KMS provider |
-| [aws.accessKeyId] | <code>string</code> | An AWS Access Key |
-| [aws.secretAccessKey] | <code>string</code> | An AWS Secret Key |
+| [aws.accessKeyId] | <code>string</code> | The access key used for the AWS KMS provider |
+| [aws.secretAccessKey] | <code>string</code> | The secret access key used for the AWS KMS provider |
 | [local] | <code>object</code> | Configuration options for using 'local' as your KMS provider |
-| [local.key] | <code>Buffer</code> | A 96-byte long Buffer used for local encryption |
+| [local.key] | <code>Buffer</code> | The master key used to encrypt/decrypt data keys. A 96-byte long Buffer. |
 
 Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.
 

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Improved metrics

Lines of code

1038

increased by0.19%

Number of lines in readme file

406

increased by5.18%

Number of low supply chain risk alerts

1

decreased by-50%

Worsened metrics

Total package byte prevSize

117255

decreased by-1.31%

Dependency count

5

increased by25%

Number of package files

15

decreased by-25%

No dependency changes