feat(shell-api): adds createEncryptedCollection on Database and ClientEncryption

packages/cli-repl/test/e2e-fle.spec.ts

@@ -465,6 +465,41 @@ describe('FLE tests', () => {
       const compactResult = await shell.executeLine(`autoMongo.getDB('${dbname}').test.compactStructuredEncryptionData()`);
       expect(compactResult).to.include('ok: 1');
     });
+
+    it('creates an encrypted collection and generates data encryption keys automatically per encrypted fields', async() => {
+      const shell = TestShell.start({ args: ['--nodb', `--cryptSharedLibPath=${cryptLibrary}`] });
+      const uri = JSON.stringify(await testServer.connectionString());
+      await shell.waitForPrompt();
+      await shell.executeLine('local = { key: BinData(0, "kh4Gv2N8qopZQMQYMEtww/AkPsIrXNmEMxTrs3tUoTQZbZu4msdRUaR8U5fXD7A7QXYHcEvuu4WctJLoT+NvvV3eeIg3MD+K8H9SR794m/safgRHdIfy6PD+rFpvmFbY") }');
+      await shell.executeLine(`keyMongo = Mongo(${uri}, { \
+        keyVaultNamespace: '${dbname}.keyVault', \
+        kmsProviders: { local } \
+      });`);
+      await shell.executeLine(`secretDB = keyMongo.getDB('${dbname}')`);
+      await shell.executeLine(`var { collection, encryptedFields } = secretDB.createEncryptedCollection('secretCollection', {
+        provider: 'local',
+        createCollectionOptions: {
+          encryptedFields: {
+            fields: [{
+              keyId: null,
+              path: 'secretField',
+              bsonType: 'string'
+            }]
+          }
+        }
+      });`);
+
+      await shell.executeLine(`plainMongo = Mongo(${uri});`);
+      const collections = await shell.executeLine(`plainMongo.getDB('${dbname}').getCollectionNames()`);
+      expect(collections).to.include('enxcol_.secretCollection.ecc');
+      expect(collections).to.include('enxcol_.secretCollection.esc');
+      expect(collections).to.include('enxcol_.secretCollection.ecoc');
+      expect(collections).to.include('secretCollection');
+
+      const dekCount = await shell.executeLine(`plainMongo.getDB('${dbname}').getCollection('keyVault').countDocuments()`);
+      // Since there is only one field to be encrypted hence there would only be one DEK in our keyvault collection
+      expect(parseInt(dekCount.trim(), 10)).to.equal(1);
+    });
   });
 
   context('6.2+', () => {

packages/i18n/src/locales/en_US.ts

@@ -1022,6 +1022,11 @@ const translations: Catalog = {
               description: 'Create new collection',
               example: 'db.createCollection(\'collName\')'
             },
+            createEncryptedCollection: {
+              link: 'https://docs.mongodb.com/manual/reference/method/db.createEncryptedCollection/',
+              description: 'Creates a new collection with a list of encrypted fields each with unique and auto-created data encryption keys (DEKs). This is a utility function that internally utilises ClientEnryption.createEncryptedCollection.',
+              example: 'db.createEncryptedCollection( "collName", { "provider": "<kmsProvider>", "createCollectionOptions": { "encryptedFields": { ... }, ...<otherOptions> } })'
+            },
             createView: {
               link: 'https://docs.mongodb.com/manual/reference/method/db.createView/',
               description: 'Create new view',
@@ -2202,7 +2207,12 @@ const translations: Catalog = {
             decrypt: {
               link: 'https://docs.mongodb.com/manual/reference/method/ClientEncryption.decrypt/#ClientEncryption.decrypt',
               description: 'decrypts the encryptionValue if the current database connection was configured with access to the Key Management Service (KMS) and key vault used to encrypt encryptionValue.'
-            }
+            },
+            createEncryptedCollection: {
+              link: 'https://docs.mongodb.com/manual/reference/method/ClientEncryption.createEncryptedCollection/#ClientEncryption.createEncryptedCollection',
+              description: 'Creates a new collection with a list of encrypted fields each with unique and auto-created data encryption keys (DEKs). This method should be invoked on a connection instantiated with queryable encryption options.',
+              example: 'db.getMongo().getClientEncryption().createEncryptedCollection( "dbName", "collName", { "provider": "<kmsProvider>", "createCollectionOptions": { "encryptedFields": { ... }, ...<otherOptions> } })'
+            },
           }
         }
       }

packages/service-provider-core/package.json

@@ -40,7 +40,7 @@
     "mongodb-build-info": "^1.5.0"
   },
   "optionalDependencies": {
-    "mongodb-client-encryption": "^2.4.0"
+    "mongodb-client-encryption": "^2.5.0"
   },
   "dependency-check": {
     "entries": [

packages/service-provider-core/src/admin.ts

@@ -10,12 +10,25 @@ import type {
   DbOptions,
   ClientSessionOptions,
   ListDatabasesOptions,
-  AutoEncryptionOptions
+  AutoEncryptionOptions,
+  Collection
 } from './all-transport-types';
 import type { bson as BSON } from './index';
 import type { ReplPlatform } from './platform';
-import { FLE } from './all-fle-types';
-
+import {
+  AWSEncryptionKeyOptions,
+  AzureEncryptionKeyOptions,
+  ClientEncryption as MongoCryptClientEncryption,
+  ClientEncryptionDataKeyProvider,
+  FLE,
+  GCPEncryptionKeyOptions
+} from './all-fle-types';
+
+export interface CreateEncryptedCollectionOptions {
+  provider: ClientEncryptionDataKeyProvider,
+  createCollectionOptions: Omit<CreateCollectionOptions, 'encryptedFields'> & { encryptedFields: Document },
+  masterKey?: AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | GCPEncryptionKeyOptions;
+}
 
 export default interface Admin {
   /**
@@ -116,4 +129,14 @@ export default interface Admin {
    * The FLE options passed to the client, if any.
    */
   getFleOptions?: () => AutoEncryptionOptions | undefined;
+
+  /**
+   * The helper method to correctly access FLE implementation's createEncryptedCollection
+   */
+  createEncryptedCollection?(
+    dbName: string,
+    collName: string,
+    options: CreateEncryptedCollectionOptions,
+    libmongocrypt: MongoCryptClientEncryption
+  ): Promise<{ collection: Collection, encryptedFields: Document }>
 }

packages/service-provider-core/src/index.ts

@@ -28,6 +28,8 @@ export * from './all-fle-types';
 
 export { MapReduceOptions, FinalizeFunction } from './map-reduce-options';
 
+export { CreateEncryptedCollectionOptions } from './admin';
+
 const bson = {
   ObjectId,
   DBRef,

packages/service-provider-server/package.json

@@ -55,7 +55,7 @@
     "saslprep": "mongodb-js/saslprep#v1.0.4"
   },
   "optionalDependencies": {
-    "mongodb-client-encryption": "^2.4.0",
+    "mongodb-client-encryption": "^2.5.0",
     "kerberos": "^2.0.0"
   }
 }

packages/service-provider-server/src/cli-service-provider.spec.ts

@@ -6,6 +6,7 @@ import sinon, { StubbedInstance, stubInterface } from 'ts-sinon';
 import CliServiceProvider from './cli-service-provider';
 import ConnectionString from 'mongodb-connection-string-url';
 import { EventEmitter } from 'events';
+import type { ClientEncryption, ClientEncryptionDataKeyProvider } from '@mongosh/service-provider-core';
 
 chai.use(sinonChai);
 
@@ -600,6 +601,47 @@ describe('CliServiceProvider', () => {
     });
   });
 
+  describe('#createEncryptedCollection', () => {
+    let dbStub: StubbedInstance<Db>;
+    let clientStub: StubbedInstance<MongoClient>;
+    let libmongoc: StubbedInstance<ClientEncryption>;
+    const createCollOptions = {
+      provider: 'local' as ClientEncryptionDataKeyProvider,
+      createCollectionOptions: {
+        encryptedFields: {
+          fields: [{
+            path: 'ssn',
+            bsonType: 'string'
+          }]
+        }
+      }
+    };
+
+    beforeEach(() => {
+      dbStub = stubInterface<Db>();
+      clientStub = stubInterface<MongoClient>();
+      clientStub.db.returns(dbStub);
+      serviceProvider = new CliServiceProvider(clientStub, bus);
+      libmongoc = stubInterface<ClientEncryption>();
+    });
+
+    it('calls calls libmongocrypt.createEncryptedCollection', async() => {
+      await serviceProvider.createEncryptedCollection('db1', 'coll1', createCollOptions, libmongoc);
+      expect(libmongoc.createEncryptedCollection).calledOnceWithExactly(
+        dbStub,
+        'coll1',
+        createCollOptions
+      );
+    });
+
+    it('returns whatever libmongocrypt.createEncryptedCollection returns', async() => {
+      const resolvedValue = { collection: { name: 'secretCol' }, encryptedFields: [] } as any;
+      libmongoc.createEncryptedCollection.resolves(resolvedValue);
+      const returnValue = await serviceProvider.createEncryptedCollection('db1', 'coll1', createCollOptions, libmongoc);
+      expect(returnValue).to.deep.equal(resolvedValue);
+    });
+  });
+
   describe('sessions', () => {
     let clientStub: StubbedInstance<MongoClient>;
     let serviceProvider: CliServiceProvider;

packages/service-provider-server/src/cli-service-provider.ts

@@ -75,7 +75,8 @@ import {
   ChangeStream,
   bson as BSON,
   FLE,
-  AutoEncryptionOptions
+  AutoEncryptionOptions,
+  ClientEncryption as MongoCryptClientEncryption
 } from '@mongosh/service-provider-core';
 
 import { connectMongoClient, DevtoolsConnectOptions } from '@mongodb-js/devtools-connect';
@@ -84,6 +85,7 @@ import type { MongoshBus } from '@mongosh/types';
 import { forceCloseMongoClient } from './mongodb-patches';
 import ConnectionString from 'mongodb-connection-string-url';
 import { EventEmitter } from 'events';
+import { CreateEncryptedCollectionOptions } from '@mongosh/service-provider-core';
 
 const bsonlib = {
   Binary,
@@ -1038,6 +1040,19 @@ class CliServiceProvider extends ServiceProviderCore implements ServiceProvider
     return { ok: 1 };
   }
 
+  async createEncryptedCollection(
+    dbName: string,
+    collName: string,
+    options: CreateEncryptedCollectionOptions,
+    libmongocrypt: MongoCryptClientEncryption
+  ): Promise<{ collection: Collection, encryptedFields: Document }> {
+    return await libmongocrypt.createEncryptedCollection(
+      this.db(dbName),
+      collName,
+      options
+    );
+  }
+
   // eslint-disable-next-line @typescript-eslint/require-await
   async initializeBulkOp(
     dbName: string,

packages/shell-api/src/database.spec.ts

@@ -14,12 +14,14 @@ import {
   bson,
   ClientSession as ServiceProviderSession,
   Document,
+  ClientEncryptionDataKeyProvider,
 } from '@mongosh/service-provider-core';
 import ShellInstanceState from './shell-instance-state';
 import crypto from 'crypto';
 import { ADMIN_DB } from './enums';
 import ChangeStreamCursor from './change-stream-cursor';
 import { CommonErrors, MongoshDeprecatedError, MongoshInvalidInputError, MongoshRuntimeError, MongoshUnimplementedError } from '@mongosh/errors';
+import { ClientEncryption } from './field-level-encryption';
 chai.use(sinonChai);
 
 describe('Database', () => {
@@ -1157,6 +1159,36 @@ describe('Database', () => {
         expect(caughtError).to.equal(expectedError);
       });
     });
+    describe('createEncryptedCollection', () => {
+      let clientEncryption: StubbedInstance<ClientEncryption>;
+      const createCollectionOptions = {
+        provider: 'local' as ClientEncryptionDataKeyProvider,
+        createCollectionOptions: {
+          encryptedFields: {
+            fields: []
+          }
+        }
+      };
+      beforeEach(() => {
+        clientEncryption = stubInterface<ClientEncryption>();
+        sinon.stub(database._mongo, 'getClientEncryption').returns(clientEncryption);
+      });
+      it('calls ClientEncryption.createEncryptedCollection with the provided options', async() => {
+        await database.createEncryptedCollection('secretCollection', createCollectionOptions);
+        expect(clientEncryption.createEncryptedCollection).calledOnceWithExactly(
+          database._name,
+          'secretCollection',
+          createCollectionOptions
+        );
+      });
+
+      it('returns whatever ClientEncryption.createEncryptedCollection returns', async() => {
+        const resolvedValue = { collection: { name: 'secretCol' }, encryptedFields: [] } as any;
+        clientEncryption.createEncryptedCollection.resolves(resolvedValue);
+        const returnValue = await database.createEncryptedCollection('secretCollection', createCollectionOptions);
+        expect(returnValue).to.deep.equal(resolvedValue);
+      });
+    });
     describe('createView', () => {
       it('calls serviceProvider.createCollection on the database without options', async() => {
         await database.createView('newcoll', 'sourcecoll', [{ $match: { x: 1 } }]);
@@ -2763,6 +2795,7 @@ describe('Database', () => {
       'copyDatabase',
       'getReplicationInfo',
       'setSecondaryOk',
+      'createEncryptedCollection',
       'sql'
     ];
     const args = [ {}, {}, {} ];

packages/shell-api/src/database.ts

@@ -48,6 +48,7 @@ import { HIDDEN_COMMANDS } from '@mongosh/history';
 import Session from './session';
 import ChangeStreamCursor from './change-stream-cursor';
 import { ShellApiErrors } from './error-codes';
+import { CreateEncryptedCollectionOptions } from '@mongosh/service-provider-core';
 
 export type CollectionNamesWithTypes = {
   name: string;
@@ -617,6 +618,17 @@ export default class Database extends ShellApiWithMongoClass {
     }
   }
 
+  @returnsPromise
+  @apiVersions([1])
+  async createEncryptedCollection(name: string, options: CreateEncryptedCollectionOptions): Promise<{ collection: Collection, encryptedFields: Document }> {
+    this._emitDatabaseApiCall('createEncryptedCollection', { name: name, options: options });
+    return this._mongo.getClientEncryption().createEncryptedCollection(
+      this._name,
+      name,
+      options
+    );
+  }
+
   async _improveErrorMessageForLowServerVersionForQE(err: Error): Promise<void> {
     try {
       const serverVersion = await this.version();