WIP feat(NODE-7059): add support for text queries with queryable encryption

.evergreen/install-mongodb-client-encryption.sh

@@ -9,7 +9,7 @@ if [ -z ${PROJECT_DIRECTORY+omitted} ]; then echo "PROJECT_DIRECTORY is unset" &
 source $DRIVERS_TOOLS/.evergreen/init-node-and-npm-env.sh
 
 rm -rf mongodb-client-encryption
-git clone https://github.com/mongodb-js/mongodb-client-encryption.git
+git clone https://github.com/baileympearson/mongodb-client-encryption.git -b NODE-7059
 pushd mongodb-client-encryption
 
 node --version

src/client-side-encryption/client_encryption.ts

@@ -591,14 +591,14 @@ export class ClientEncryption {
         field == null || typeof field !== 'object' || field.keyId != null
           ? field
           : {
-              ...field,
-              keyId: await this.createDataKey(provider, {
-                masterKey,
-                // clone the timeoutContext
-                // in order to avoid sharing the same timeout for server selection and connection checkout across different concurrent operations
-                timeoutContext: timeoutContext?.csotEnabled() ? timeoutContext?.clone() : undefined
-              })
-            }
+            ...field,
+            keyId: await this.createDataKey(provider, {
+              masterKey,
+              // clone the timeoutContext
+              // in order to avoid sharing the same timeout for server selection and connection checkout across different concurrent operations
+              timeoutContext: timeoutContext?.csotEnabled() ? timeoutContext?.clone() : undefined
+            })
+          }
       );
       const createDataKeyResolutions = await Promise.allSettled(createDataKeyPromises);
 
@@ -749,7 +749,8 @@ export class ClientEncryption {
     expressionMode: boolean,
     options: ClientEncryptionEncryptOptions
   ): Promise<Binary> {
-    const { algorithm, keyId, keyAltName, contentionFactor, queryType, rangeOptions } = options;
+    const { algorithm, keyId, keyAltName, contentionFactor, queryType, rangeOptions, textOptions } =
+      options;
     const contextOptions: ExplicitEncryptionContextOptions = {
       expressionMode,
       algorithm
@@ -782,6 +783,11 @@ export class ClientEncryption {
       contextOptions.rangeOptions = serialize(rangeOptions);
     }
 
+    if (typeof textOptions === 'object') {
+      // @ts-expect-error errors until mongodb-client-encryption release
+      contextOptions.textOptions = serialize(textOptions);
+    }
+
     const valueBuffer = serialize({ v: value });
     const stateMachine = new StateMachine({
       proxyOptions: this._proxyOptions,
@@ -808,11 +814,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'
-    | 'Range';
+  | 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic'
+  | 'AEAD_AES_256_CBC_HMAC_SHA_512-Random'
+  | 'Indexed'
+  | 'Unindexed'
+  | 'Range'
+  | 'TextPreview';
 
   /**
    * The id of the Binary dataKey to use for encryption
@@ -830,10 +837,33 @@ export interface ClientEncryptionEncryptOptions {
   /**
    * The query type.
    */
-  queryType?: 'equality' | 'range';
+  queryType?: 'equality' | 'range' | 'prefixPreview' | 'suffixPreview' | 'substringPreview';
 
   /** The index options for a Queryable Encryption field supporting "range" queries.*/
   rangeOptions?: RangeOptions;
+
+  textOptions?: TextQueryOptions;
+}
+
+interface TextQueryOptions {
+  caseSensitive: boolean;
+  diacriticSensitive: boolean;
+
+  prefix?: {
+    strMaxQueryLength: Int32 | number;
+    strMinQueryLength: Int32 | number;
+  };
+
+  suffix?: {
+    strMaxQueryLength: Int32 | number;
+    strMinQueryLength: Int32 | number;
+  };
+
+  substring?: {
+    strMaxLength: Int32 | number;
+    strMaxQueryLength: Int32 | number;
+    strMinQueryLength: Int32 | number;
+  };
 }
 
 /**
@@ -843,11 +873,11 @@ export interface ClientEncryptionEncryptOptions {
 export interface ClientEncryptionRewrapManyDataKeyProviderOptions {
   provider: ClientEncryptionDataKeyProvider;
   masterKey?:
-    | AWSEncryptionKeyOptions
-    | AzureEncryptionKeyOptions
-    | GCPEncryptionKeyOptions
-    | KMIPEncryptionKeyOptions
-    | undefined;
+  | AWSEncryptionKeyOptions
+  | AzureEncryptionKeyOptions
+  | GCPEncryptionKeyOptions
+  | KMIPEncryptionKeyOptions
+  | undefined;
 }
 
 /**
@@ -1036,11 +1066,11 @@ export interface ClientEncryptionCreateDataKeyProviderOptions {
    * Identifies a new KMS-specific key used to encrypt the new data key
    */
   masterKey?:
-    | AWSEncryptionKeyOptions
-    | AzureEncryptionKeyOptions
-    | GCPEncryptionKeyOptions
-    | KMIPEncryptionKeyOptions
-    | undefined;
+  | AWSEncryptionKeyOptions
+  | AzureEncryptionKeyOptions
+  | GCPEncryptionKeyOptions
+  | KMIPEncryptionKeyOptions
+  | undefined;
 
   /**
    * An optional list of string alternate names used to reference a key.

test/integration/client-side-encryption/client_side_encryption.prose.27.text_queries.test.ts

@@ -0,0 +1,180 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { type Binary, type Document, EJSON } from 'bson';
+import { expect } from 'chai';
+
+import { getCSFLEKMSProviders } from '../../csfle-kms-providers';
+import {
+  ClientEncryption,
+  type ClientEncryptionEncryptOptions,
+  type MongoClient
+} from '../../mongodb';
+
+const metadata: MongoDBMetadataUI = {
+  requires: {
+    clientSideEncryption: '>=6.4.0',
+    mongodb: '>=8.2.0',
+    topology: '!single'
+  }
+};
+
+const loadFLEDataFile = (filename: string) =>
+  readFile(join(__dirname, '../../spec/client-side-encryption/etc/data', filename), {
+    encoding: 'utf-8'
+  });
+
+describe.only('27. Text Explicit Encryption', function () {
+  let encryptedFields: Document;
+  let keyDocument1: Document;
+  let keyId1: Binary;
+  let client: MongoClient;
+  let keyVaultClient: MongoClient;
+  let clientEncryption: ClientEncryption;
+  let encryptedClient: MongoClient;
+  let encryptOpts: ClientEncryptionEncryptOptions;
+
+  beforeEach(async function () {
+    encryptedFields = EJSON.parse(await loadFLEDataFile('encryptedFields-prefix-suffix.json'), {
+      relaxed: false
+    });
+    keyDocument1 = EJSON.parse(await loadFLEDataFile('keys/key1-document.json'), {
+      relaxed: false
+    });
+
+    keyId1 = keyDocument1._id;
+    client = this.configuration.newClient();
+
+    await client
+      .db('db')
+      .dropCollection('explicit_encryption', { writeConcern: { w: 'majority' }, encryptedFields });
+    await client.db('db').createCollection('explicit_encryption', {
+      writeConcern: { w: 'majority' },
+      encryptedFields
+    });
+
+    // Drop and create the collection `keyvault.datakeys`.
+    // Insert `key1Document` in `keyvault.datakeys` with majority write concern.
+    await client.db('keyvault').dropCollection('datakeys', { writeConcern: { w: 'majority' } });
+    await client.db('keyvault').createCollection('datakeys', { writeConcern: { w: 'majority' } });
+    await client
+      .db('keyvault')
+      .collection('datakeys')
+      .insertOne(keyDocument1, { writeConcern: { w: 'majority' } });
+
+    // Create a MongoClient named `keyVaultClient`.
+    keyVaultClient = this.configuration.newClient();
+
+    // Create a ClientEncryption object named `clientEncryption` with these options:
+    // class ClientEncryptionOpts {
+    //    keyVaultClient: <keyVaultClient>,
+    //    keyVaultNamespace: "keyvault.datakeys",
+    //    kmsProviders: { "local": { "key": <base64 decoding of LOCAL_MASTERKEY> } },
+    // }
+    clientEncryption = new ClientEncryption(keyVaultClient, {
+      keyVaultNamespace: 'keyvault.datakeys',
+      kmsProviders: {
+        local: getCSFLEKMSProviders().local
+      }
+    });
+
+    // Create a MongoClient named `encryptedClient` with these `AutoEncryptionOpts`:
+    // class AutoEncryptionOpts {
+    //    keyVaultNamespace: "keyvault.datakeys",
+    //    kmsProviders: { "local": { "key": <base64 decoding of LOCAL_MASTERKEY> } },
+    //    bypassQueryAnalysis: true,
+    // }
+    encryptedClient = this.configuration.newClient(
+      {},
+      {
+        autoEncryption: {
+          keyVaultNamespace: 'keyvault.datakeys',
+          kmsProviders: {
+            local: getCSFLEKMSProviders().local
+          },
+          bypassQueryAnalysis: true
+        }
+      }
+    );
+
+    encryptOpts = {
+      keyId: keyId1,
+      contentionFactor: 0,
+      algorithm: 'TextPreview',
+      textOptions: {
+        caseSensitive: true,
+        diacriticSensitive: true,
+        prefix: {
+          strMaxQueryLength: 10,
+          strMinQueryLength: 2
+        },
+        suffix: {
+          strMaxQueryLength: 10,
+          strMinQueryLength: 2
+        },
+        substring: {
+          strMaxLength: 10,
+          strMaxQueryLength: 10,
+          strMinQueryLength: 2
+        }
+      }
+    };
+
+    const encryptedText = await clientEncryption.encrypt('foobarbaz', {
+      keyId: keyId1,
+      algorithm: 'TextPreview',
+      contentionFactor: 0,
+      textOptions: {
+        caseSensitive: true,
+        diacriticSensitive: true,
+        prefix: {
+          strMaxQueryLength: 10,
+          strMinQueryLength: 2
+        },
+        suffix: {
+          strMaxQueryLength: 10,
+          strMinQueryLength: 2
+        }
+      }
+    });
+
+    await encryptedClient
+      .db('db')
+      .collection<{ _id: number; encryptedText: Binary }>('explicit_encryption')
+      .insertOne({
+        _id: 0,
+        encryptedText
+      });
+  });
+
+  afterEach(async function () {
+    await Promise.allSettled([client.close(), encryptedClient.close(), keyVaultClient.close()]);
+  });
+
+  it('works', async function () {
+    const encryptedFoo = await clientEncryption.encrypt('foo', {
+      keyId: keyId1,
+      algorithm: 'TextPreview',
+      contentionFactor: 0,
+      textOptions: {
+        caseSensitive: true,
+        diacriticSensitive: true,
+        prefix: {
+          strMaxQueryLength: 10,
+          strMinQueryLength: 2
+        }
+      }
+    });
+
+    const filter = {
+      $expr: { $encStrStartsWith: { input: 'encryptedText', prefix: encryptedFoo } }
+    };
+
+    expect(
+      await encryptedClient
+        .db('db')
+        .collection<{ _id: number; encryptedText: Binary }>('explicit_encryption')
+        .findOne(filter)
+    ).to.deep.equal({ _id: 0, encryptedText: 'foobarbaz' });
+  });
+});

test/spec/client-side-encryption/etc/data/encryptedFields-prefix-suffix.json

@@ -0,0 +1,38 @@
+{
+    "fields": [
+        {
+            "keyId": {
+                "$binary": {
+                    "base64": "EjRWeBI0mHYSNBI0VniQEg==",
+                    "subType": "04"
+                }
+            },
+            "path": "encryptedText",
+            "bsonType": "string",
+            "queries": [
+                {
+                    "queryType": "prefixPreview",
+                    "strMinQueryLength": {
+                        "$numberInt": "2"
+                    },
+                    "strMaxQueryLength": {
+                        "$numberInt": "10"
+                    },
+                    "caseSensitive": true,
+                    "diacriticSensitive": true
+                },
+                {
+                    "queryType": "suffixPreview",
+                    "strMinQueryLength": {
+                        "$numberInt": "2"
+                    },
+                    "strMaxQueryLength": {
+                        "$numberInt": "10"
+                    },
+                    "caseSensitive": true,
+                    "diacriticSensitive": true
+                }
+            ]
+        }
+    ]
+}

test/spec/client-side-encryption/etc/data/encryptedFields-substring.json

@@ -0,0 +1,30 @@
+{
+  "fields": [
+    {
+            "keyId": {
+                "$binary": {
+                    "base64": "EjRWeBI0mHYSNBI0VniQEg==",
+                    "subType": "04"
+                }
+            },
+            "path": "encrypted-textPreview",
+            "bsonType": "string",
+            "queries": [
+                {
+                    "queryType": "substringPreview",
+                    "strMaxLength": {
+                        "$numberInt": "10"
+                    },
+                    "strMinQueryLength": {
+                        "$numberInt": "2"
+                    },
+                    "strMaxQueryLength": {
+                        "$numberInt": "10"
+                    },
+                    "caseSensitive": true,
+                    "diacriticSensitive": true
+                }
+            ]
+        }
+  ]
+}