feat(NODE-6506): Add support for encrypted schemas

[baileympearson]

Summary

This PR adds support for declaring encrypted schemas, as the first step in adding first class support for CSFLE to mongoose. Functionally:

1. A new schema option, encryptionType, has been added. This is required for schemas that are declaring encrypted fields, and it determines whether the schema will be configured for 'csfle' or 'qe'.
2. Keys in schemas can now be configured with an additional encrypt option. This option contains metadata for libmongocrypt to encrypt the field (which will be automatically included in a schemaMap or encryptedFieldsMap). The contents of this document are exactly the same as the fields used to configure a field for csfle or qe, except that bsonType is not required (inferred from the schema type).

This PR also updates all the schema modifiers / cloning methods to account for updating encrypted fields as well.

Examples

Declare an encrypted schema:

const encryptedSchema = new Schema({
  name: { type: String, encrypt: { keyId: '...' } },
  friend: { 
      // nested objects allowed
      name: { type: String, encrypt: { keyId: '...' } },
  },
  // arrays allowed - but becase of how CSFLE/QE encrypted arrays, the arrays are encrypted as a whole
  books: { type: [String], encrypt: { keyId: '...' } }
}, { encryptionType: 'qe' });

Modify / clone encrypted schemas

encryptedSchema.clone();

encryptedSchema.add({ name: String }) // name is no longer encrypted
encryptedSchema.add({ newKey: { type: String, encrypt: { keyId: '...' } }); // new encrypted key added

encryptedSchema.remove('name'); // name no longer in schema at all

encryptedSchema.pick('friends'); // returns a new schema with only one field, `friends`, that is encrypted.

encryptedSchema.omit('friends'); // returns a new schema with all fields except `frields`

[baileympearson]

I added .config because I noticed lint failed after generating the docs locally, and data because otherwise the data for encrypted tests is linted.

[vkarpov15]

Can we instead add these as a getBSONType() method on SchemaType class? That would make this more extensible for custom schematypes.

[baileympearson]

I can instead make it a getter on SchemaType - but this isn't intended to be extensible for custom schema types (see the When a schema is instantiated with a custom schema type plugin test).

FLE has pretty strict requirements about which bson types are supported and I intentionally only supported the exact schema type that correspond to FLE's supported schema types. Allowing users to provide custom schema types that get auto encrypted seems like it could confusion for users and opaque errors. A hypothetical scenario: a custom schema type sometimes casts to a support BSON type, sometimes it doesn't, causing FLE to throw only sometimes for users.

I'm open to reconsidering though - we could instead support any SchemaType that casts to exactly one supported BSON type. I'm not sure we could enforce this programmatically but documentation would probably suffice. Would you prefer that approach?

[vkarpov15]

For consistency, please name this file lib/encryptionUtils.js, Mongoose camelCases file names

[baileympearson]

Does this apply to test files too?

[vkarpov15]

Mongoose document arrays get implicitly created schemas, so docArr: [{ name: String }] implicitly creates a schema with { name: String }. We pass certain schema options to implicitly created schemas, like typeKey. It might be worthwhile to make sure encryption type gets passed down as well.

[baileympearson]

Arrays are encrypted as an array, not by individual element. So the logic here only creates a schemaType of type "array" - the contents of the array don't matter. So encryptionType for the implicitly generated schemas shouldn't matter.

That being said, I'm happy to ensure that the encryption type gets propagated to sub-schemas if you'd like

[vkarpov15]

Why is _encryptionType a separate property, instead of making encryptionType() get/set options.encryptionType? The latter would be more consistent with how Mongoose handles other options.

[baileympearson]

Only because I didn't consider mutation the options object 🙂 . Fixed!

[aditi-khare-mongoDB]

Suggested change

	MongoDB has to different automatic encryption implementations: client side field level encryption (CSFLE) and queryable encryption (QE).
	MongoDB has two different automatic encryption implementations: client side field level encryption (CSFLE) and queryable encryption (QE).

[aditi-khare-mongoDB]

If we only pick unencrypted fields, the resulting schema's options.encryptionType is null.

With the current implementation, if we omit all encrypted fields, the resulting schema's options.encryptionType is not null. What's our reasoning for this?