mongoose 8.14.3 → 8.15.1

package/lib/schema/decimal128.js

@@ -235,6 +235,10 @@ SchemaDecimal128.prototype.toJSONSchema = function toJSONSchema(options) {
   return createJSONSchemaTypeDefinition('string', 'decimal', options?.useBsonType, isRequired);
 };
 
+SchemaDecimal128.prototype.autoEncryptionType = function autoEncryptionType() {
+  return 'decimal';
+};
+
 /*!
  * Module exports.
  */

package/lib/schema/double.js

@@ -218,6 +218,10 @@ SchemaDouble.prototype.toJSONSchema = function toJSONSchema(options) {
   return createJSONSchemaTypeDefinition('number', 'double', options?.useBsonType, isRequired);
 };
 
+SchemaDouble.prototype.autoEncryptionType = function autoEncryptionType() {
+  return 'double';
+};
+
 /*!
  * Module exports.
  */

package/lib/schema/int32.js

@@ -260,6 +260,10 @@ SchemaInt32.prototype.toJSONSchema = function toJSONSchema(options) {
   return createJSONSchemaTypeDefinition('number', 'int', options?.useBsonType, isRequired);
 };
 
+SchemaInt32.prototype.autoEncryptionType = function autoEncryptionType() {
+  return 'int';
+};
+
 
 /*!
  * Module exports.

package/lib/schema/map.js

@@ -95,6 +95,10 @@ class SchemaMap extends SchemaType {
 
     return result;
   }
+
+  autoEncryptionType() {
+    return 'object';
+  }
 }
 
 /**

package/lib/schema/objectId.js

@@ -304,6 +304,10 @@ SchemaObjectId.prototype.toJSONSchema = function toJSONSchema(options) {
   return createJSONSchemaTypeDefinition('string', 'objectId', options?.useBsonType, isRequired);
 };
 
+SchemaObjectId.prototype.autoEncryptionType = function autoEncryptionType() {
+  return 'objectId';
+};
+
 /*!
  * Module exports.
  */

package/lib/schema/string.js

@@ -712,6 +712,10 @@ SchemaString.prototype.toJSONSchema = function toJSONSchema(options) {
   return createJSONSchemaTypeDefinition('string', 'string', options?.useBsonType, isRequired);
 };
 
+SchemaString.prototype.autoEncryptionType = function autoEncryptionType() {
+  return 'string';
+};
+
 /*!
  * Module exports.
  */

package/lib/schema/uuid.js

@@ -298,6 +298,10 @@ SchemaUUID.prototype.toJSONSchema = function toJSONSchema(options) {
   return createJSONSchemaTypeDefinition('string', 'binData', options?.useBsonType, isRequired);
 };
 
+SchemaUUID.prototype.autoEncryptionType = function autoEncryptionType() {
+  return 'binData';
+};
+
 /*!
  * Module exports.
  */

package/lib/schema.js

@@ -86,6 +86,7 @@ const numberRE = /^\d+$/;
  * - [pluginTags](https://mongoosejs.com/docs/guide.html#pluginTags): array of strings - defaults to `undefined`. If set and plugin called with `tags` option, will only apply that plugin to schemas with a matching tag.
  * - [virtuals](https://mongoosejs.com/docs/tutorials/virtuals.html#virtuals-via-schema-options): object - virtuals to define, alias for [`.virtual`](https://mongoosejs.com/docs/api/schema.html#Schema.prototype.virtual())
  * - [collectionOptions]: object with options passed to [`createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection/) when calling `Model.createCollection()` or `autoCreate` set to true.
+ * - [encryptionType]: the encryption type for the schema.  Valid options are `csfle` or `queryableEncryption`.  See https://mongoosejs.com/docs/field-level-encryption.
  *
  * #### Options for Nested Schemas:
  *
@@ -128,6 +129,7 @@ function Schema(obj, options) {
   // For internal debugging. Do not use this to try to save a schema in MDB.
   this.$id = ++id;
   this.mapPaths = [];
+  this.encryptedFields = {};
 
   this.s = {
     hooks: new Kareem()
@@ -463,6 +465,8 @@ Schema.prototype._clone = function _clone(Constructor) {
 
   s.aliases = Object.assign({}, this.aliases);
 
+  s.encryptedFields = clone(this.encryptedFields);
+
   return s;
 };
 
@@ -495,7 +499,16 @@ Schema.prototype.pick = function(paths, options) {
   }
 
   for (const path of paths) {
-    if (this.nested[path]) {
+    if (this._hasEncryptedField(path)) {
+      const encrypt = this.encryptedFields[path];
+      const schemaType = this.path(path);
+      newSchema.add({
+        [path]: {
+          encrypt,
+          [this.options.typeKey]: schemaType
+        }
+      });
+    } else if (this.nested[path]) {
       newSchema.add({ [path]: get(this.tree, path) });
     } else {
       const schematype = this.path(path);
@@ -506,6 +519,10 @@ Schema.prototype.pick = function(paths, options) {
     }
   }
 
+  if (!this._hasEncryptedFields()) {
+    newSchema.options.encryptionType = null;
+  }
+
   return newSchema;
 };
 
@@ -667,6 +684,22 @@ Schema.prototype._defaultToObjectOptions = function(json) {
   return defaultOptions;
 };
 
+/**
+ * Sets the encryption type of the schema, if a value is provided, otherwise
+ * returns the encryption type.
+ *
+ * @param {'csfle' | 'queryableEncryption' | null | undefined} encryptionType plain object with paths to add, or another schema
+ */
+Schema.prototype.encryptionType = function encryptionType(encryptionType) {
+  if (arguments.length === 0) {
+    return this.options.encryptionType;
+  }
+  if (!(typeof encryptionType === 'string' || encryptionType === null)) {
+    throw new Error('invalid `encryptionType`: ${encryptionType}');
+  }
+  this.options.encryptionType = encryptionType;
+};
+
 /**
  * Adds key path / schema type pairs to this schema.
  *
@@ -689,7 +722,6 @@ Schema.prototype._defaultToObjectOptions = function(json) {
 Schema.prototype.add = function add(obj, prefix) {
   if (obj instanceof Schema || (obj != null && obj.instanceOfSchema)) {
     merge(this, obj);
-
     return this;
   }
 
@@ -818,6 +850,31 @@ Schema.prototype.add = function add(obj, prefix) {
         }
       }
     }
+
+    if (val.instanceOfSchema && val.encryptionType() != null) {
+      // schema.add({ field: <instance of encrypted schema> })
+      if (this.encryptionType() != val.encryptionType()) {
+        throw new Error('encryptionType of a nested schema must match the encryption type of the parent schema.');
+      }
+
+      for (const [encryptedField, encryptedFieldConfig] of Object.entries(val.encryptedFields)) {
+        const path = fullPath + '.' + encryptedField;
+        this._addEncryptedField(path, encryptedFieldConfig);
+      }
+    } else if (typeof val === 'object' && 'encrypt' in val) {
+      // schema.add({ field: { type: <schema type>, encrypt: { ... }}})
+      const { encrypt } = val;
+
+      if (this.encryptionType() == null) {
+        throw new Error('encryptionType must be provided');
+      }
+
+      this._addEncryptedField(fullPath, encrypt);
+    } else {
+      // if the field was already encrypted and we re-configure it to be unencrypted, remove
+      // the encrypted field configuration
+      this._removeEncryptedField(fullPath);
+    }
   }
 
   const aliasObj = Object.fromEntries(
@@ -827,6 +884,117 @@ Schema.prototype.add = function add(obj, prefix) {
   return this;
 };
 
+/**
+ * @param {string} path
+ * @param {object} fieldConfig
+ *
+ * @api private
+ */
+Schema.prototype._addEncryptedField = function _addEncryptedField(path, fieldConfig) {
+  const type = this.path(path).autoEncryptionType();
+  if (type == null) {
+    throw new Error(`Invalid BSON type for FLE field: '${path}'`);
+  }
+
+  this.encryptedFields[path] = clone(fieldConfig);
+};
+
+/**
+ * @param {string} path
+ *
+ * @api private
+ */
+Schema.prototype._removeEncryptedField = function _removeEncryptedField(path) {
+  delete this.encryptedFields[path];
+};
+
+/**
+ * @api private
+ *
+ * @returns {boolean}
+ */
+Schema.prototype._hasEncryptedFields = function _hasEncryptedFields() {
+  return Object.keys(this.encryptedFields).length > 0;
+};
+
+/**
+ * @param {string} path
+ * @returns {boolean}
+ *
+ * @api private
+ */
+Schema.prototype._hasEncryptedField = function _hasEncryptedField(path) {
+  return path in this.encryptedFields;
+};
+
+
+/**
+ * Builds an encryptedFieldsMap for the schema.
+ *
+ * @api private
+ */
+Schema.prototype._buildEncryptedFields = function() {
+  const fields = Object.entries(this.encryptedFields).map(
+    ([path, config]) => {
+      const bsonType = this.path(path).autoEncryptionType();
+      // { path, bsonType, keyId, queries? }
+      return { path, bsonType, ...config };
+    });
+
+  return { fields };
+};
+
+/**
+ * Builds a schemaMap for the schema, if the schema is configured for client-side field level encryption.
+ *
+ * @api private
+ */
+Schema.prototype._buildSchemaMap = function() {
+  /**
+   * `schemaMap`s are JSON schemas, which use the following structure to represent objects:
+   *    { field: { bsonType: 'object', properties: { ... } } }
+   *
+   * for example, a schema that looks like this `{ a: { b: int32 } }` would be encoded as
+   * `{ a: { bsonType: 'object', properties: { b: < encryption configuration > } } }`
+   *
+   * This function takes an array of path segments, an output object (that gets mutated) and
+   * a value to be associated with the full path, and constructs a valid CSFLE JSON schema path for
+   * the object.  This works for deeply nested properties as well.
+   *
+   * @param {string[]} path array of path components
+   * @param {object} object the object in which to build a JSON schema of `path`'s properties
+   * @param {object} value the value to associate with the path in object
+   */
+  function buildNestedPath(path, object, value) {
+    let i = 0, component = path[i];
+    for (; i < path.length - 1; ++i, component = path[i]) {
+      object[component] = object[component] == null ? {
+        bsonType: 'object',
+        properties: {}
+      } : object[component];
+      object = object[component].properties;
+    }
+    object[component] = value;
+  }
+
+  const schemaMapPropertyReducer = (accum, [path, propertyConfig]) => {
+    const bsonType = this.path(path).autoEncryptionType();
+    const pathComponents = path.split('.');
+    const configuration = { encrypt: { ...propertyConfig, bsonType } };
+    buildNestedPath(pathComponents, accum, configuration);
+    return accum;
+  };
+
+  const properties = Object.entries(this.encryptedFields).reduce(
+    schemaMapPropertyReducer,
+    {});
+
+  return {
+    bsonType: 'object',
+    properties
+  };
+};
+
 /**
  * Add an alias for `path`. This means getting or setting the `alias`
  * is equivalent to getting or setting the `path`.
@@ -1378,6 +1546,16 @@ Schema.prototype.interpretAsType = function(path, obj, options) {
   let type = obj[options.typeKey] && (obj[options.typeKey] instanceof Function || options.typeKey !== 'type' || !obj.type.type)
     ? obj[options.typeKey]
     : {};
+
+  if (type instanceof SchemaType) {
+    if (type.path === path) {
+      return type;
+    }
+    const clone = type.clone();
+    clone.path = path;
+    return clone;
+  }
+
   let name;
 
   if (utils.isPOJO(type) || type === 'mixed') {
@@ -2523,6 +2701,8 @@ Schema.prototype.remove = function(path) {
 
       delete this.paths[name];
       _deletePath(this, name);
+
+      this._removeEncryptedField(name);
     }, this);
   }
   return this;

package/lib/schemaType.js

@@ -1783,6 +1783,14 @@ SchemaType.prototype.toJSONSchema = function toJSONSchema() {
   throw new Error('Converting unsupported SchemaType to JSON Schema: ' + this.instance);
 };
 
+/**
+ * Returns the BSON type that the schema corresponds to, for automatic encryption.
+ * @api private
+ */
+SchemaType.prototype.autoEncryptionType = function autoEncryptionType() {
+  return null;
+};
+
 /*!
  * Module exports.
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "8.14.3",
+  "version": "8.15.1",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -31,6 +31,7 @@
   "devDependencies": {
     "@babel/core": "7.27.1",
     "@babel/preset-env": "7.27.1",
+    "@mongodb-js/mongodb-downloader": "^0.3.9",
     "@typescript-eslint/eslint-plugin": "^8.19.1",
     "@typescript-eslint/parser": "^8.19.1",
     "acquit": "1.3.0",
@@ -58,6 +59,7 @@
     "mocha": "11.2.2",
     "moment": "2.30.1",
     "mongodb-memory-server": "10.1.4",
+    "mongodb-runner": "^5.8.2",
     "ncp": "^2.0.0",
     "nyc": "15.1.0",
     "pug": "3.0.3",
@@ -104,7 +106,7 @@
     "test-deno": "deno run --allow-env --allow-read --allow-net --allow-run --allow-sys --allow-write ./test/deno.mjs",
     "test-rs": "START_REPLICA_SET=1 mocha --timeout 30000 --exit ./test/*.test.js",
     "test-tsd": "node ./test/types/check-types-filename && tsd",
-    "setup-test-encryption": "bash scripts/configure-cluster-with-encryption.sh",
+    "setup-test-encryption": "node scripts/setup-encryption-tests.js",
     "test-encryption": "mocha --exit ./test/encryption/*.test.js",
     "tdd": "mocha ./test/*.test.js --inspect --watch --recursive --watch-files ./**/*.{js,ts}",
     "test-coverage": "nyc --reporter=html --reporter=text npm test",

package/types/index.d.ts

@@ -657,9 +657,43 @@ declare module 'mongoose' {
 
   export type ReturnsNewDoc = { new: true } | { returnOriginal: false } | { returnDocument: 'after' };
 
-  export type ProjectionElementType = number | string;
-  export type ProjectionType<T> = { [P in keyof T]?: ProjectionElementType } | AnyObject | string;
-
+  type ArrayOperators = { $slice: number | [number, number]; $elemMatch?: never } | { $elemMatch: Record<string, any>; $slice?: never };
+  /**
+   * This Type Assigns `Element | undefined` recursively to the `T` type.
+   * if it is an array it will do this to the element of the array, if it is an object it will do this for the properties of the object.
+   * `Element` is the truthy or falsy values that are going to be used as the value of the projection.(1 | true or 0 | false)
+   * For the elements of the array we will use: `Element | `undefined` | `ArrayOperators`
+   * @example
+   * type CalculatedType = Projector<{ a: string, b: number, c: { d: string }, d: string[] }, true>
+   * type CalculatedType = {
+        a?: true | undefined;
+        b?: true | undefined;
+        c?: true | {
+            d?: true | undefined;
+        } | undefined;
+        d?: true | ArrayOperators | undefined;
+    }
+  */
+  type Projector<T, Element> = T extends Array<infer U>
+    ? Projector<U, Element> | ArrayOperators
+    : T extends TreatAsPrimitives
+      ? Element
+      : T extends Record<string, any>
+        ? {
+          [K in keyof T]?: T[K] extends Record<string, any> ? Projector<T[K], Element> | Element : Element;
+        }
+        : Element;
+  type _IDType = { _id?: boolean | 1 | 0 };
+  export type InclusionProjection<T> = IsItRecordAndNotAny<T> extends true
+    ? Omit<Projector<WithLevel1NestedPaths<T>, true | 1>, '_id'> & _IDType
+    : AnyObject;
+  export type ExclusionProjection<T> = IsItRecordAndNotAny<T> extends true
+    ? Omit<Projector<WithLevel1NestedPaths<T>, false | 0>, '_id'> & _IDType
+    : AnyObject;
+
+  export type ProjectionType<T> = (InclusionProjection<T> & AnyObject)
+    | (ExclusionProjection<T> & AnyObject)
+    | string;
   export type SortValues = SortOrder;
 
   export type SortOrder = -1 | 1 | 'asc' | 'ascending' | 'desc' | 'descending';

package/types/models.d.ts

@@ -919,5 +919,11 @@ declare module 'mongoose' {
       'find',
       TInstanceMethods & TVirtuals
     >;
+
+    /**
+     * If auto encryption is enabled, returns a ClientEncryption instance that is configured with the same settings that
+     * Mongoose's underlying MongoClient is using.  If the client has not yet been configured, returns null.
+     */
+    clientEncryption(): mongodb.ClientEncryption | null;
   }
 }

package/types/pipelinestage.d.ts

@@ -319,10 +319,11 @@ declare module 'mongoose' {
     export interface VectorSearch {
       /** [`$vectorSearch` reference](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/) */
       $vectorSearch: {
+        exact?: boolean;
         index: string,
         path: string,
         queryVector: number[],
-        numCandidates: number,
+        numCandidates?: number,
         limit: number,
         filter?: Expression,
       }

package/types/query.d.ts

@@ -160,7 +160,7 @@ declare module 'mongoose' {
      * Set `overwriteImmutable` to `true` to allow updating immutable properties using other update operators.
      */
     overwriteImmutable?: boolean;
-    projection?: ProjectionType<DocType>;
+    projection?: { [P in keyof DocType]?: number | string } | AnyObject | string;
     /**
      * if true, returns the full ModifyResult rather than just the document
      */

package/types/schemaoptions.d.ts

@@ -259,6 +259,11 @@ declare module 'mongoose' {
      * @default false
      */
     overwriteModels?: boolean;
+
+    /**
+     *  Required when the schema is encrypted.
+     */
+    encryptionType?: 'csfle' | 'queryableEncryption';
   }
 
   interface DefaultSchemaOptions {

package/types/schematypes.d.ts

@@ -1,3 +1,5 @@
+import * as BSON from 'bson';
+
 declare module 'mongoose' {
 
   /** The Mongoose Date [SchemaType](/docs/schematypes.html). */
@@ -210,6 +212,11 @@ declare module 'mongoose' {
     maxlength?: number | [number, string] | readonly [number, string];
 
     [other: string]: any;
+
+    /**
+     * If set, configures the field for automatic encryption.
+     */
+    encrypt?: EncryptSchemaTypeOptions;
   }
 
   interface Validator<DocType = any> {
@@ -221,6 +228,28 @@ declare module 'mongoose' {
 
   type ValidatorFunction<DocType = any> = (this: DocType, value: any, validatorProperties?: Validator) => any;
 
+  interface QueryEncryptionEncryptOptions {
+    /** The id of the dataKey to use for encryption.  Must be a BSON binary subtype 4 (UUID). */
+    keyId: BSON.Binary;
+
+    /**
+     * Specifies the type of queries that the field can be queried on the encrypted field.
+    */
+    queries?: 'equality' | 'range';
+  }
+
+  interface ClientSideEncryptionEncryptOptions {
+    /** The id of the dataKey to use for encryption.  Must be a BSON binary subtype 4 (UUID). */
+    keyId: [BSON.Binary];
+
+    /**
+     * The algorithm to use for encryption.
+     */
+    algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' | 'AEAD_AES_256_CBC_HMAC_SHA_512-Random';
+  }
+
+  export type EncryptSchemaTypeOptions = QueryEncryptionEncryptOptions | ClientSideEncryptionEncryptOptions;
+
   class SchemaType<T = any, DocType = any> {
     /** SchemaType constructor */
     constructor(path: string, options?: AnyObject, instance?: string);

package/types/types.d.ts

@@ -60,7 +60,7 @@ declare module 'mongoose' {
 
     class Decimal128 extends mongodb.Decimal128 { }
 
-    class DocumentArray<T, THydratedDocumentType extends Types.Subdocument<any> = Types.Subdocument<InferId<T>, any, T> & T> extends Types.Array<THydratedDocumentType> {
+    class DocumentArray<T, THydratedDocumentType extends Types.Subdocument<any, any, T> = Types.Subdocument<InferId<T>, any, T> & T> extends Types.Array<THydratedDocumentType> {
       /** DocumentArray constructor */
       constructor(values: AnyObject[]);
 
@@ -85,7 +85,7 @@ declare module 'mongoose' {
     class ObjectId extends mongodb.ObjectId {
     }
 
-    class Subdocument<IdType = unknown, TQueryHelpers = any, DocType = any> extends Document<IdType, TQueryHelpers, DocType> {
+    class Subdocument<IdType = any, TQueryHelpers = any, DocType = any> extends Document<IdType, TQueryHelpers, DocType> {
       $isSingleNested: true;
 
       /** Returns the top level document of this sub-document. */

package/types/utility.d.ts

@@ -4,20 +4,44 @@ declare module 'mongoose' {
 
   type WithLevel1NestedPaths<T, K extends keyof T = keyof T> = {
     [P in K | NestedPaths<Required<T>, K>]: P extends K
-      ? T[P]
+      // Handle top-level paths
+      // First, drill into documents so we don't end up surfacing `$assertPopulated`, etc.
+      ? Extract<NonNullable<T[P]>, Document> extends never
+        // If not a document, then return the type. Otherwise, get the DocType.
+        ? NonNullable<T[P]>
+        : Extract<NonNullable<T[P]>, Document> extends Document<any, any, infer DocType, any>
+          ? DocType
+          : never
+      // Handle nested paths
       : P extends `${infer Key}.${infer Rest}`
         ? Key extends keyof T
-          ? Rest extends keyof NonNullable<T[Key]>
-            ? NonNullable<T[Key]>[Rest]
-            : never
+          ? T[Key] extends (infer U)[]
+            ? Rest extends keyof NonNullable<U>
+              ? NonNullable<U>[Rest]
+              : never
+            : Rest extends keyof NonNullable<T[Key]>
+              ? NonNullable<T[Key]>[Rest]
+              : never
           : never
         : never;
   };
 
   type NestedPaths<T, K extends keyof T> = K extends string
-    ? T[K] extends Record<string, any> | null | undefined
-      ? `${K}.${keyof NonNullable<T[K]> & string}`
-      : never
+    ? T[K] extends TreatAsPrimitives
+      ? never
+      : Extract<NonNullable<T[K]>, Document> extends never
+          ? T[K] extends Array<infer U>
+            ? U extends Record<string, any>
+              ? `${K}.${keyof NonNullable<U> & string}`
+              : never
+            : T[K] extends Record<string, any> | null | undefined
+              ? `${K}.${keyof NonNullable<T[K]> & string}`
+              : never
+          : Extract<NonNullable<T[K]>, Document> extends Document<any, any, infer DocType, any>
+            ? DocType extends Record<string, any>
+              ? `${K}.${keyof NonNullable<DocType> & string}`
+              : never
+            : never
     : never;
 
   type WithoutUndefined<T> = T extends undefined ? never : T;