all changes

Author: baileympearson

.eslintrc.js

@@ -14,7 +14,9 @@ module.exports = {
     '**/docs/js/native.js',
     '!.*',
     'node_modules',
-    '.git'
+    '.git',
+    'data',
+    '.config'
   ],
   overrides: [
     {

.github/workflows/encryption-tests.yml

@@ -0,0 +1,37 @@
+name: Encryption Tests 
+
+on:
+  push: 
+    branches: ['master']
+  pull_request:
+    branches: [ 'master' ]
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  run-tests:
+    permissions:
+      # required for all workflows
+      security-events: write
+      id-token: write
+      contents: write
+    runs-on: ubuntu-latest
+    name: Encryption tests
+    env:
+      FORCE_COLOR: true
+    steps:
+      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 # v4.2.0
+      - name: Setup node
+        uses: actions/setup-node@0a44ba7841725637a19e28fa30b79a866c81b0a6 # v4.0.4
+        with:
+          node-version: 22
+      - name: Install Dependencies
+        run: npm install
+      - name: Install mongodb-client-encryption
+        run: npm install mongodb-client-encryption
+      - name: Run Tests
+        run: npm run test-encryption

.gitignore

@@ -67,3 +67,6 @@ examples/ecommerce-netlify-functions/.netlify/state.json
 
 notes.md
 list.out
+
+data
+*.pid

CONTRIBUTING.md

@@ -46,6 +46,7 @@ If you have a question about Mongoose (not a bug report) please post it to eithe
   * execute `npm run test-tsd` to run the typescript tests
   * execute `npm run ts-benchmark` to run the typescript benchmark "performance test" for a single time.
   * execute `npm run ts-benchmark-watch` to run the typescript benchmark "performance test" while watching changes on types folder. Note: Make sure to commit all changes before executing this command.
+* in order to run tests that require an cluster with encryption locally, run `npm run test-encryption`. Alternatively, you can start an encrypted cluster using the `scripts/configure-cluster-with-encryption.sh` file.
 
 ## Documentation
 

docs/field-level-encryption.md

@@ -112,3 +112,51 @@ With the above connection, if you create a model named 'Test' that uses the 'tes
 const Model = mongoose.model('Test', mongoose.Schema({ name: String }));
 await Model.create({ name: 'super secret' });
 ```
+
+## Automatic FLE in Mongoose
+
+Mongoose supports the declaration of encrypted schemas - schemas that, when connected to a model, utilize MongoDB's Client Side
+Field Level Encryption or Queryable Encryption under the hood.  Mongoose automatically generates either an `encryptedFieldsMap` or a
+`schemaMap` when instantiating a MongoClient and encrypts fields on write and decrypts fields on reads.
+
+### Encryption types
+
+MongoDB has to different automatic encryption implementations: client side field level encryption (CSFLE) and queryable encryption (QE).  
+See [choosing an in-use encryption approach](https://www.mongodb.com/docs/v7.3/core/queryable-encryption/about-qe-csfle/#choosing-an-in-use-encryption-approach).
+
+###  Declaring Encrypted Schemas
+
+The following schema declares two properties, `name` and `ssn`.  `ssn` is encrypted using queryable encryption, and
+is configured for equality queries:
+
+```javascript
+const encryptedUserSchema = new Schema({ 
+  name: String,
+  ssn: { 
+    type: String, 
+    // 1
+    encrypt: { 
+      keyId: '<uuid string of key id>',
+      queries: 'equality'
+    }
+  }
+  // 2
+}, { encryptionType: 'queryable encryption' });
+```
+
+To declare a field as encrypted, you must:
+
+1. Annotate the field with encryption metadata in the schema definition
+2. Choose an encryption type for the schema and configure the schema for the encryption type
+
+Not all schematypes are supported for CSFLE and QE.  For an overview of valid schema types, refer to MongoDB's documentation.
+
+### Registering Models
+
+Encrypted schemas must be registered on a connection, not the Mongoose global:
+
+```javascript
+
+const connection = mongoose.createConnection();
+const UserModel = connection.model('User', encryptedUserSchema);
+```

lib/collection.js

@@ -81,7 +81,7 @@ Collection.prototype.onOpen = function() {
  * @api private
  */
 
-Collection.prototype.onClose = function() {};
+Collection.prototype.onClose = function() { };
 
 /**
  * Queues a method for later execution when its

lib/connection.js

@@ -607,7 +607,7 @@ Connection.prototype.bulkWrite = async function bulkWrite(ops, options) {
 
 Connection.prototype.createCollections = async function createCollections(options = {}) {
   const result = {};
-  const errorsMap = { };
+  const errorsMap = {};
 
   const { continueOnError } = options;
   delete options.continueOnError;
@@ -734,7 +734,7 @@ Connection.prototype.transaction = function transaction(fn, options) {
         throw err;
       }).
       finally(() => {
-        session.endSession().catch(() => {});
+        session.endSession().catch(() => { });
       });
   });
 };
@@ -1025,7 +1025,7 @@ Connection.prototype.openUri = async function openUri(uri, options) {
 
   for (const model of Object.values(this.models)) {
     // Errors handled internally, so safe to ignore error
-    model.init().catch(function $modelInitNoop() {});
+    model.init().catch(function $modelInitNoop() { });
   }
 
   // `createConnection()` calls this `openUri()` function without
@@ -1061,7 +1061,7 @@ Connection.prototype.openUri = async function openUri(uri, options) {
 // to avoid uncaught exceptions when using `on('error')`. See gh-14377.
 Connection.prototype.on = function on(event, callback) {
   if (event === 'error' && this.$initialConnection) {
-    this.$initialConnection.catch(() => {});
+    this.$initialConnection.catch(() => { });
   }
   return EventEmitter.prototype.on.call(this, event, callback);
 };
@@ -1083,7 +1083,7 @@ Connection.prototype.on = function on(event, callback) {
 // to avoid uncaught exceptions when using `on('error')`. See gh-14377.
 Connection.prototype.once = function on(event, callback) {
   if (event === 'error' && this.$initialConnection) {
-    this.$initialConnection.catch(() => {});
+    this.$initialConnection.catch(() => { });
   }
   return EventEmitter.prototype.once.call(this, event, callback);
 };
@@ -1412,7 +1412,7 @@ Connection.prototype.model = function model(name, schema, collection, options) {
     }
 
     // Errors handled internally, so safe to ignore error
-    model.init().catch(function $modelInitNoop() {});
+    model.init().catch(function $modelInitNoop() { });
 
     return model;
   }
@@ -1439,7 +1439,7 @@ Connection.prototype.model = function model(name, schema, collection, options) {
   }
 
   if (this === model.prototype.db
-      && (!collection || collection === model.collection.name)) {
+    && (!collection || collection === model.collection.name)) {
     // model already uses this connection.
 
     // only the first model with this name is cached to allow
@@ -1626,8 +1626,8 @@ Connection.prototype.authMechanismDoesNotRequirePassword = function authMechanis
  */
 Connection.prototype.optionsProvideAuthenticationData = function optionsProvideAuthenticationData(options) {
   return (options) &&
-      (options.user) &&
-      ((options.pass) || this.authMechanismDoesNotRequirePassword());
+    (options.user) &&
+    ((options.pass) || this.authMechanismDoesNotRequirePassword());
 };
 
 /**
@@ -1689,7 +1689,7 @@ Connection.prototype.createClient = function createClient() {
  */
 Connection.prototype.syncIndexes = async function syncIndexes(options = {}) {
   const result = {};
-  const errorsMap = { };
+  const errorsMap = {};
 
   const { continueOnError } = options;
   delete options.continueOnError;

lib/drivers/node-mongodb-native/connection.js

@@ -304,6 +304,16 @@ NativeConnection.prototype.createClient = async function createClient(uri, optio
     };
   }
 
+  const { schemaMap, encryptedFieldsMap } = this._buildEncryptionSchemas();
+
+  if (Object.keys(schemaMap).length > 0) {
+    options.autoEncryption.schemaMap = schemaMap;
+  }
+
+  if (Object.keys(encryptedFieldsMap).length > 0) {
+    options.autoEncryption.encryptedFieldsMap = encryptedFieldsMap;
+  }
+
   this.readyState = STATES.connecting;
   this._connectionString = uri;
 
@@ -327,6 +337,40 @@ NativeConnection.prototype.createClient = async function createClient(uri, optio
   return this;
 };
 
+/**
+ * Given a connection, which may or may not have encrypted models, build
+ * a schemaMap and/or an encryptedFieldsMap for the connection, combining all models
+ * into a single schemaMap and encryptedFields map.
+ *
+ * @returns a copy of the options object with a schemaMap and/or an encryptedFieldsMap added to the options' autoEncryption
+ * options.
+  */
+NativeConnection.prototype._buildEncryptionSchemas = function() {
+  const schemaMap = Object.values(this.models).filter(model => model.schema.encryptionType() === 'csfle').reduce(
+    (schemaMap, model) => {
+      const { schema, collection: { collectionName } } = model;
+      const namespace = `${this.$dbName}.${collectionName}`;
+      schemaMap[namespace] = schema._buildSchemaMap();
+      return schemaMap;
+    },
+    {}
+  );
+
+  const encryptedFieldsMap = Object.values(this.models).filter(model => model.schema.encryptionType() === 'qe').reduce(
+    (encryptedFieldsMap, model) => {
+      const { schema, collection: { collectionName } } = model;
+      const namespace = `${this.$dbName}.${collectionName}`;
+      encryptedFieldsMap[namespace] = schema._buildEncryptedFields();
+      return encryptedFieldsMap;
+    },
+    {}
+  );
+
+  return {
+    schemaMap, encryptedFieldsMap
+  };
+};
+
 /*!
  * ignore
  */
@@ -347,7 +391,7 @@ NativeConnection.prototype.setClient = function setClient(client) {
 
   for (const model of Object.values(this.models)) {
     // Errors handled internally, so safe to ignore error
-    model.init().catch(function $modelInitNoop() {});
+    model.init().catch(function $modelInitNoop() { });
   }
 
   return this;
@@ -390,9 +434,9 @@ function _setClient(conn, client, options, dbName) {
   };
 
   const type = client &&
-  client.topology &&
-  client.topology.description &&
-  client.topology.description.type || '';
+    client.topology &&
+    client.topology.description &&
+    client.topology.description.type || '';
 
   if (type === 'Single') {
     client.on('serverDescriptionChanged', ev => {

lib/encryption_utils.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const { Array } = require('./schema/index.js');
+const SchemaBigInt = require('./schema/bigint');
+const SchemaBoolean = require('./schema/boolean');
+const SchemaBuffer = require('./schema/buffer');
+const SchemaDate = require('./schema/date');
+const SchemaDecimal128 = require('./schema/decimal128');
+const SchemaDouble = require('./schema/double');
+const SchemaInt32 = require('./schema/int32');
+const SchemaObjectId = require('./schema/objectId');
+const SchemaString = require('./schema/string');
+
+/**
+ * Given a schema and a path to a field in the schema, this returns the
+ * BSON type of the field, if it can be determined.  This method specifically
+ * **only** handles BSON types that are used for CSFLE and QE - any other
+ * BSON types will return `null`. (example: MinKey and MaxKey).
+ *
+ * @param {import('.').Schema} schema
+ * @param {string} path
+ * @returns
+ */
+function inferBSONType(schema, path) {
+  const type = schema.path(path);
+
+  if (type instanceof SchemaString) {
+    return 'string';
+  }
+
+  if (type instanceof SchemaInt32) {
+    return 'int';
+  }
+
+  if (type instanceof SchemaBigInt) {
+    return 'long';
+  }
+
+  if (type instanceof SchemaBoolean) {
+    return 'bool';
+  }
+
+  if (type instanceof SchemaDate) {
+    return 'date';
+  }
+
+  if (type instanceof SchemaBuffer) {
+    return 'binData';
+  }
+
+  if (type instanceof SchemaObjectId) {
+    return 'objectId';
+  }
+
+  if (type instanceof SchemaDecimal128) {
+    return 'decimal';
+  }
+
+  if (type instanceof SchemaDouble) {
+    return 'double';
+  }
+
+  if (type instanceof Array) {
+    return 'array';
+  }
+
+  return null;
+}
+
+module.exports = {
+  inferBSONType
+};