libmongocrypt-helper 1.7.4.0.1001 → 1.8.0.0.1001

data/ext/libmongocrypt/libmongocrypt/bindings/node/index.d.ts

@@ -1,5 +1,15 @@
-import type { Document, Binary } from 'bson';
-import type { MongoClient, BulkWriteResult, ClientSession, DeleteResult, FindCursor } from 'mongodb';
+import type {
+  MongoClient,
+  BulkWriteResult,
+  DeleteResult,
+  FindCursor,
+  Collection,
+  Db,
+  CreateCollectionOptions,
+  Document,
+  Binary,
+  Long
+} from 'mongodb';
 
 export type ClientEncryptionDataKeyProvider = 'aws' | 'azure' | 'gcp' | 'local' | 'kmip';
 
@@ -21,8 +31,47 @@ export interface DataKey {
  * An error indicating that something went wrong specifically with MongoDB Client Encryption
  */
 export class MongoCryptError extends Error {
+  cause?: Error;
 }
 
+/**
+ * @experimental Public Technical Preview
+ * An error indicating that `ClientEncryption.createEncryptedCollection()` failed to create a collection
+ */
+export class MongoCryptCreateEncryptedCollectionError extends MongoCryptError {
+  /**
+   * @experimental Public Technical Preview
+   * The entire `encryptedFields` that was completed while attempting createEncryptedCollection
+   */
+  encryptedFields: Document;
+  /** The error rejected from db.createCollection() */
+  cause: Error;
+}
+
+/**
+ * @experimental Public Technical Preview
+ * An error indicating that `ClientEncryption.createEncryptedCollection()` failed to create data keys
+ */
+export class MongoCryptCreateDataKeyError extends MongoCryptError {
+  /**
+   * @experimental Public Technical Preview
+   * The partial `encryptedFields` that was completed while attempting createEncryptedCollection
+   */
+  encryptedFields: Document;
+  /** The first error encountered when attempting to `createDataKey` */
+  cause: Error;
+}
+
+/**
+ * An error indicating that mongodb-client-encryption failed to auto-refresh Azure KMS credentials.
+ */
+export class MongoCryptAzureKMSRequestError extends MongoCryptError {
+  /* The body of the IMDS request that produced the error, if present. */
+  body?: Document ;
+}
+
+export class MongoCryptKMSRequestNetworkTimeoutError extends MongoCryptError {}
+
 /**
  * A set of options for specifying a Socks5 proxy.
  */
@@ -64,23 +113,25 @@ export interface KMSProviders {
   /**
    * Configuration options for using 'aws' as your KMS provider
    */
-  aws?: {
-    /**
-     * The access key used for the AWS KMS provider
-     */
-    accessKeyId: string;
+  aws?:
+    | {
+        /**
+         * The access key used for the AWS KMS provider
+         */
+        accessKeyId: string;
 
-    /**
-     * The secret access key used for the AWS KMS provider
-     */
-    secretAccessKey: string;
+        /**
+         * The secret access key used for the AWS KMS provider
+         */
+        secretAccessKey: string;
 
-    /**
-     * An optional AWS session token that will be used as the
-     * X-Amz-Security-Token header for AWS requests.
-     */
-    sessionToken?: string;
-  };
+        /**
+         * An optional AWS session token that will be used as the
+         * X-Amz-Security-Token header for AWS requests.
+         */
+        sessionToken?: string;
+      }
+    | Record<string, never>;
 
   /**
    * Configuration options for using 'local' as your KMS provider
@@ -108,51 +159,67 @@ export interface KMSProviders {
   /**
    * Configuration options for using 'azure' as your KMS provider
    */
-  azure?: {
-    /**
-     * The tenant ID identifies the organization for the account
-     */
-    tenantId: string;
-
-    /**
-     * The client ID to authenticate a registered application
-     */
-    clientId: string;
-
-    /**
-     * The client secret to authenticate a registered application
-     */
-    clientSecret: string;
-
-    /**
-     * If present, a host with optional port. E.g. "example.com" or "example.com:443".
-     * This is optional, and only needed if customer is using a non-commercial Azure instance
-     * (e.g. a government or China account, which use different URLs).
-     * Defaults to "login.microsoftonline.com"
-     */
-    identityPlatformEndpoint?: string | undefined;
-  };
+  azure?:
+    | {
+        /**
+         * The tenant ID identifies the organization for the account
+         */
+        tenantId: string;
+
+        /**
+         * The client ID to authenticate a registered application
+         */
+        clientId: string;
+
+        /**
+         * The client secret to authenticate a registered application
+         */
+        clientSecret: string;
+
+        /**
+         * If present, a host with optional port. E.g. "example.com" or "example.com:443".
+         * This is optional, and only needed if customer is using a non-commercial Azure instance
+         * (e.g. a government or China account, which use different URLs).
+         * Defaults to "login.microsoftonline.com"
+         */
+        identityPlatformEndpoint?: string | undefined;
+      }
+    | {
+        /**
+         * If present, an access token to authenticate with Azure.
+         */
+        accessToken: string;
+      }
+    | Record<string, never>;
 
   /**
    * Configuration options for using 'gcp' as your KMS provider
    */
-  gcp?: {
-    /**
-     * The service account email to authenticate
-     */
-    email: string;
-
-    /**
-     * A PKCS#8 encrypted key. This can either be a base64 string or a binary representation
-     */
-    privateKey: string | Buffer;
-
-    /**
-     * If present, a host with optional port. E.g. "example.com" or "example.com:443".
-     * Defaults to "oauth2.googleapis.com"
-     */
-    endpoint?: string | undefined;
-  }
+  gcp?:
+    | {
+        /**
+         * The service account email to authenticate
+         */
+        email: string;
+
+        /**
+         * A PKCS#8 encrypted key. This can either be a base64 string or a binary representation
+         */
+        privateKey: string | Buffer;
+
+        /**
+         * If present, a host with optional port. E.g. "example.com" or "example.com:443".
+         * Defaults to "oauth2.googleapis.com"
+         */
+        endpoint?: string | undefined;
+      }
+    | {
+        /**
+         * If present, an access token to authenticate with GCP.
+         */
+        accessToken: string;
+      }
+    | Record<string, never>;
 }
 
 /**
@@ -304,9 +371,13 @@ export interface AzureEncryptionKeyOptions {
  */
 export interface ClientEncryptionCreateDataKeyProviderOptions {
   /**
-   * Idenfities a new KMS-specific key used to encrypt the new data key
+   * Identifies a new KMS-specific key used to encrypt the new data key
    */
-  masterKey?: AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | GCPEncryptionKeyOptions | undefined;
+  masterKey?:
+    | AWSEncryptionKeyOptions
+    | AzureEncryptionKeyOptions
+    | GCPEncryptionKeyOptions
+    | undefined;
 
   /**
    * An optional list of string alternate names used to reference a key.
@@ -321,7 +392,11 @@ export interface ClientEncryptionCreateDataKeyProviderOptions {
 /** @experimental */
 export interface ClientEncryptionRewrapManyDataKeyProviderOptions {
   provider: ClientEncryptionDataKeyProvider;
-  masterKey?: AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | GCPEncryptionKeyOptions | undefined;
+  masterKey?:
+    | AWSEncryptionKeyOptions
+    | AzureEncryptionKeyOptions
+    | GCPEncryptionKeyOptions
+    | undefined;
 }
 
 /** @experimental */
@@ -330,6 +405,18 @@ export interface ClientEncryptionRewrapManyDataKeyResult {
   bulkWriteResult?: BulkWriteResult;
 }
 
+/**
+ * RangeOptions specifies index options for a Queryable Encryption field supporting "rangePreview" queries.
+ * min, max, sparsity, and range must match the values set in the encryptedFields of the destination collection.
+ * For double and decimal128, min/max/precision must all be set, or all be unset.
+ */
+interface RangeOptions {
+  min?: any;
+  max?: any;
+  sparsity: Long;
+  precision?: number;
+}
+
 /**
  * Options to provide when encrypting data.
  */
@@ -337,7 +424,12 @@ export interface ClientEncryptionEncryptOptions {
   /**
    * The algorithm to use for encryption.
    */
-  algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' | 'AEAD_AES_256_CBC_HMAC_SHA_512-Random' | 'Indexed' | 'Unindexed';
+  algorithm:
+    | 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic'
+    | 'AEAD_AES_256_CBC_HMAC_SHA_512-Random'
+    | 'Indexed'
+    | 'Unindexed'
+    | 'RangePreview';
 
   /**
    * The id of the Binary dataKey to use for encryption
@@ -353,7 +445,10 @@ export interface ClientEncryptionEncryptOptions {
   contentionFactor?: bigint | number;
 
   /** @experimental Public Technical Preview: The query type supported */
-  queryType?: 'equality';
+  queryType?: 'equality' | 'rangePreview';
+
+  /** @experimental Public Technical Preview: The index options for a Queryable Encryption field supporting "rangePreview" queries.*/
+  rangeOptions?: RangeOptions;
 }
 
 /**
@@ -371,9 +466,7 @@ export class ClientEncryption {
    * Creates a data key used for explicit encryption and inserts it into the key vault namespace
    * @param provider The KMS provider used for this data key. Must be `'aws'`, `'azure'`, `'gcp'`, or `'local'`
    */
-  createDataKey(
-    provider: ClientEncryptionDataKeyProvider
-  ): Promise<Binary>;
+  createDataKey(provider: ClientEncryptionDataKeyProvider): Promise<Binary>;
 
   /**
    * Creates a data key used for explicit encryption and inserts it into the key vault namespace
@@ -467,6 +560,30 @@ export class ClientEncryption {
    */
   removeKeyAltName(id: Binary, keyAltName: string): Promise<DataKey | null>;
 
+  /**
+   * @experimental Public Technical Preview
+   * A convenience method for creating an encrypted collection.
+   * This method will create data keys for any encryptedFields that do not have a `keyId` defined
+   * and then create a new collection with the full set of encryptedFields.
+   *
+   * @param db - A Node.js driver Db object with which to create the collection
+   * @param name - The name of the new collection
+   * @param options - Options for createDataKey and for createCollection. A provider and partially created encryptedFields **must** be provided.
+   * @throws {MongoCryptCreateDataKeyForEncryptedCollectionError} - If part way through the process a createDataKey invocation fails, an error will be rejected that has the partial `encryptedFields` that were created.
+   * @throws {MongoCryptCreateEncryptedCollectionError} - If creating the collection fails, an error will be rejected that has the entire `encryptedFields` that were created.
+   */
+  createEncryptedCollection<TSchema extends Document = Document>(
+    db: Db,
+    name: string,
+    options: {
+      provider: ClientEncryptionDataKeyProvider;
+      createCollectionOptions: Omit<CreateCollectionOptions, 'encryptedFields'> & {
+        encryptedFields: Document;
+      };
+      masterKey?: AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | GCPEncryptionKeyOptions;
+    }
+  ): Promise<{ collection: Collection<TSchema>; encryptedFields: Document }>;
+
   /**
    * Explicitly encrypt a provided value.
    * Note that either options.keyId or options.keyAltName must be specified.
@@ -474,10 +591,7 @@ export class ClientEncryption {
    * @param value The value that you wish to serialize. Must be of a type that can be serialized into BSON
    * @param options
    */
-  encrypt(
-    value: any,
-    options: ClientEncryptionEncryptOptions
-  ): Promise<Binary>;
+  encrypt(value: any, options: ClientEncryptionEncryptOptions): Promise<Binary>;
 
   /**
    * Explicitly encrypt a provided value.
@@ -493,23 +607,35 @@ export class ClientEncryption {
     callback: ClientEncryptionEncryptCallback
   ): void;
 
+  /**
+   * Encrypts a Match Expression or Aggregate Expression to query a range index.
+   *
+   * Only supported when queryType is "rangePreview" and algorithm is "RangePreview".
+   *
+   * @experimental The Range algorithm is experimental only. It is not intended for production use. It is subject to breaking changes.The aggregation or match expression you wish to encrypt.  The value must be in the form
+   *
+   * The expression to encrypt must be one of the following:
+   *  1. A Match Expression of this form:
+   *      `{$and: [{<field>: {$gt: <value1>}}, {<field>: {$lt: <value2> }}]}`
+   *  2. An Aggregate Expression of this form:
+   *      `{$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}]}`
+   *
+   *    `$gt` may also be `$gte`. `$lt` may also be `$lte`.
+   */
+  encryptExpression(value: Document, options: ClientEncryptionEncryptOptions): Promise<Document>;
+
   /**
    * Explicitly decrypt a provided encrypted value
    * @param value An encrypted value
    */
-  decrypt(
-    value: Buffer | Binary
-  ): Promise<any>;
+  decrypt(value: Buffer | Binary): Promise<any>;
 
   /**
    * Explicitly decrypt a provided encrypted value
    * @param value An encrypted value
    * @param callback Callback to invoke when value is decrypted
    */
-  decrypt(
-    value: Buffer | Binary,
-    callback: ClientEncryptionDecryptCallback
-  ): void;
+  decrypt(value: Buffer | Binary, callback: ClientEncryptionDecryptCallback): void;
 
   static readonly libmongocryptVersion: string;
 }

data/ext/libmongocrypt/libmongocrypt/bindings/node/lib/autoEncrypter.js

@@ -9,7 +9,7 @@ module.exports = function (modules) {
   const MongoClient = modules.mongodb.MongoClient;
   const MongoError = modules.mongodb.MongoError;
   const BSON = modules.mongodb.BSON;
-  const { loadCredentials } = require('./credentialsProvider');
+  const { loadCredentials } = require('./providers/index');
   const cryptoCallbacks = require('./cryptoCallbacks');
 
   /**

data/ext/libmongocrypt/libmongocrypt/bindings/node/lib/clientEncryption.js

@@ -6,12 +6,20 @@ module.exports = function (modules) {
   const databaseNamespace = common.databaseNamespace;
   const collectionNamespace = common.collectionNamespace;
   const promiseOrCallback = common.promiseOrCallback;
+  const maybeCallback = common.maybeCallback;
   const StateMachine = modules.stateMachine.StateMachine;
   const BSON = modules.mongodb.BSON;
-  const { loadCredentials } = require('./credentialsProvider');
+  const {
+    MongoCryptCreateEncryptedCollectionError,
+    MongoCryptCreateDataKeyError
+  } = require('./errors');
+  const { loadCredentials } = require('./providers/index');
   const cryptoCallbacks = require('./cryptoCallbacks');
   const { promisify } = require('util');
 
+  /** @typedef {*} BSONValue - any serializable BSON value */
+  /** @typedef {BSON.Long} Long A 64 bit integer, represented by the js-bson Long type.*/
+
   /**
    * @typedef {object} KMSProviders Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.
    * @property {object} [aws] Configuration options for using 'aws' as your KMS provider
@@ -545,21 +553,99 @@ module.exports = function (modules) {
       return value;
     }
 
+    /**
+     * @experimental Public Technical Preview
+     *
+     * A convenience method for creating an encrypted collection.
+     * This method will create data keys for any encryptedFields that do not have a `keyId` defined
+     * and then create a new collection with the full set of encryptedFields.
+     *
+     * @template {TSchema} - Schema for the collection being created
+     * @param {Db} db - A Node.js driver Db object with which to create the collection
+     * @param {string} name - The name of the collection to be created
+     * @param {object} options - Options for createDataKey and for createCollection
+     * @param {string} options.provider - KMS provider name
+     * @param {AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | GCPEncryptionKeyOptions} [options.masterKey] - masterKey to pass to createDataKey
+     * @param {CreateCollectionOptions} options.createCollectionOptions - options to pass to createCollection, must include `encryptedFields`
+     * @returns {Promise<{ collection: Collection<TSchema>, encryptedFields: Document }>} - created collection and generated encryptedFields
+     * @throws {MongoCryptCreateDataKeyError} - If part way through the process a createDataKey invocation fails, an error will be rejected that has the partial `encryptedFields` that were created.
+     * @throws {MongoCryptCreateEncryptedCollectionError} - If creating the collection fails, an error will be rejected that has the entire `encryptedFields` that were created.
+     */
+    async createEncryptedCollection(db, name, options) {
+      const {
+        provider,
+        masterKey,
+        createCollectionOptions: {
+          encryptedFields: { ...encryptedFields },
+          ...createCollectionOptions
+        }
+      } = options;
+
+      if (Array.isArray(encryptedFields.fields)) {
+        const createDataKeyPromises = encryptedFields.fields.map(async field =>
+          field == null || typeof field !== 'object' || field.keyId != null
+            ? field
+            : {
+                ...field,
+                keyId: await this.createDataKey(provider, { masterKey })
+              }
+        );
+
+        const createDataKeyResolutions = await Promise.allSettled(createDataKeyPromises);
+
+        encryptedFields.fields = createDataKeyResolutions.map((resolution, index) =>
+          resolution.status === 'fulfilled' ? resolution.value : encryptedFields.fields[index]
+        );
+
+        const rejection = createDataKeyResolutions.find(({ status }) => status === 'rejected');
+        if (rejection != null) {
+          throw new MongoCryptCreateDataKeyError({ encryptedFields, cause: rejection.reason });
+        }
+      }
+
+      try {
+        const collection = await db.createCollection(name, {
+          ...createCollectionOptions,
+          encryptedFields
+        });
+        return { collection, encryptedFields };
+      } catch (cause) {
+        throw new MongoCryptCreateEncryptedCollectionError({ encryptedFields, cause });
+      }
+    }
+
     /**
      * @callback ClientEncryptionEncryptCallback
      * @param {Error} [err] If present, indicates an error that occurred in the process of encryption
      * @param {Buffer} [result] If present, is the encrypted result
      */
 
+    /**
+     * @typedef {object} RangeOptions
+     * min, max, sparsity, and range must match the values set in the encryptedFields of the destination collection.
+     * For double and decimal128, min/max/precision must all be set, or all be unset.
+     * @property {BSONValue} min is required if precision is set.
+     * @property {BSONValue} max is required if precision is set.
+     * @property {BSON.Long} sparsity
+     * @property {number | undefined} precision (may only be set for double or decimal128).
+     */
+
+    /**
+     * @typedef {object} EncryptOptions Options to provide when encrypting data.
+     * @property {ClientEncryptionDataKeyId} [keyId] The id of the Binary dataKey to use for encryption.
+     * @property {string} [keyAltName] A unique string name corresponding to an already existing dataKey.
+     * @property {string} [algorithm] The algorithm to use for encryption. Must be either `'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic'`, `'AEAD_AES_256_CBC_HMAC_SHA_512-Random'`, `'Indexed'` or `'Unindexed'`
+     * @property {bigint | number} [contentionFactor] (experimental) - the contention factor.
+     * @property {'equality' | 'rangePreview'} queryType (experimental) - the query type supported.
+     * @property {RangeOptions} [rangeOptions] (experimental) The index options for a Queryable Encryption field supporting "rangePreview" queries.
+     */
+
     /**
      * 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 {ClientEncryptionDataKeyId} [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'`, `'AEAD_AES_256_CBC_HMAC_SHA_512-Random'`, `'Indexed'` or `'Unindexed'`
+     * @param {EncryptOptions} options
      * @param {ClientEncryptionEncryptCallback} [callback] Optional callback to invoke when value is encrypted
      * @returns {Promise|void} 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.
      *
@@ -589,44 +675,29 @@ module.exports = function (modules) {
      * }
      */
     encrypt(value, options, callback) {
-      const bson = this._bson;
-      const valueBuffer = bson.serialize({ v: value });
-      const contextOptions = Object.assign({}, options);
-      if (options.keyId) {
-        contextOptions.keyId = options.keyId.buffer;
-      }
-      if (options.keyAltName) {
-        const keyAltName = options.keyAltName;
-        if (options.keyId) {
-          throw new TypeError(`"options" cannot contain both "keyId" and "keyAltName"`);
-        }
-        const keyAltNameType = typeof keyAltName;
-        if (keyAltNameType !== 'string') {
-          throw new TypeError(
-            `"options.keyAltName" must be of type string, but was of type ${keyAltNameType}`
-          );
-        }
-
-        contextOptions.keyAltName = bson.serialize({ keyAltName });
-      }
-
-      const stateMachine = new StateMachine({
-        bson,
-        proxyOptions: this._proxyOptions,
-        tlsOptions: this._tlsOptions
-      });
-      const context = this._mongoCrypt.makeExplicitEncryptionContext(valueBuffer, contextOptions);
-
-      return promiseOrCallback(callback, cb => {
-        stateMachine.execute(this, context, (err, result) => {
-          if (err) {
-            cb(err, null);
-            return;
-          }
+      return maybeCallback(() => this._encrypt(value, false, options), callback);
+    }
 
-          cb(null, result.v);
-        });
-      });
+    /**
+     * Encrypts a Match Expression or Aggregate Expression to query a range index.
+     *
+     * Only supported when queryType is "rangePreview" and algorithm is "RangePreview".
+     *
+     * @experimental The Range algorithm is experimental only. It is not intended for production use. It is subject to breaking changes.
+     *
+     * @param {object} expression a BSON document of one of the following forms:
+     *  1. A Match Expression of this form:
+     *      `{$and: [{<field>: {$gt: <value1>}}, {<field>: {$lt: <value2> }}]}`
+     *  2. An Aggregate Expression of this form:
+     *      `{$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}]}`
+     *
+     *    `$gt` may also be `$gte`. `$lt` may also be `$lte`.
+     *
+     * @param {EncryptOptions} options
+     * @returns {Promise<object>} Returns a Promise that either resolves with the encrypted value or rejects with an error.
+     */
+    async encryptExpression(expression, options) {
+      return this._encrypt(expression, true, options);
     }
 
     /**
@@ -640,7 +711,7 @@ module.exports = function (modules) {
      *
      * @param {Buffer | Binary} value An encrypted value
      * @param {ClientEncryption~decryptCallback} callback Optional callback to invoke when value is decrypted
-     * @returns {Promise|void} If no callback is provided, returns a Promise that either resolves with the decryped value, 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 the decrypted value, or rejects with an error. If a callback is provided, returns nothing.
      *
      * @example
      * // Decrypting value with callback API
@@ -693,6 +764,57 @@ module.exports = function (modules) {
     static get libmongocryptVersion() {
       return mc.MongoCrypt.libmongocryptVersion;
     }
+
+    /**
+     * A helper that perform explicit encryption of values and expressions.
+     * 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 encrypt. Must be of a type that can be serialized into BSON
+     * @param {boolean} expressionMode - a boolean that indicates whether or not to encrypt the value as an expression
+     * @param {EncryptOptions} options
+     * @returns the raw result of the call to stateMachine.execute().  When expressionMode is set to true, the return
+     *          value will be a bson document.  When false, the value will be a BSON Binary.
+     *
+     * @ignore
+     *
+     */
+    async _encrypt(value, expressionMode, options) {
+      const bson = this._bson;
+      const valueBuffer = bson.serialize({ v: value });
+      const contextOptions = Object.assign({}, options, { expressionMode });
+      if (options.keyId) {
+        contextOptions.keyId = options.keyId.buffer;
+      }
+      if (options.keyAltName) {
+        const keyAltName = options.keyAltName;
+        if (options.keyId) {
+          throw new TypeError(`"options" cannot contain both "keyId" and "keyAltName"`);
+        }
+        const keyAltNameType = typeof keyAltName;
+        if (keyAltNameType !== 'string') {
+          throw new TypeError(
+            `"options.keyAltName" must be of type string, but was of type ${keyAltNameType}`
+          );
+        }
+
+        contextOptions.keyAltName = bson.serialize({ keyAltName });
+      }
+
+      if ('rangeOptions' in options) {
+        contextOptions.rangeOptions = bson.serialize(options.rangeOptions);
+      }
+
+      const stateMachine = new StateMachine({
+        bson,
+        proxyOptions: this._proxyOptions,
+        tlsOptions: this._tlsOptions
+      });
+      const context = this._mongoCrypt.makeExplicitEncryptionContext(valueBuffer, contextOptions);
+
+      const result = await stateMachine.executeAsync(this, context);
+      return result.v;
+    }
   }
 
   return { ClientEncryption };