mongoose-encrypt-fields

mongoose-encrypt-fields provides a Mongoose plugin and a custom SchemaType that encrypt and decrypt individual fields.

The goal of this plugin is to perform field-level encryption and decryption at the ODM layer, allowing applications to use it without worrying about the logic.

This plugin is for use cases where Mongoose is used in Nest.js.

flowchart LR
  subgraph app [Application]
    nestjs(Nest.js)
    mongoose([Mongoose])
    nestjs --> mongoose
    mongoose ---|encrypt/decrypt using plugin and custom SchemaType| mongoose
  end
  mongodb[(MongoDB)]

  mongoose --> mongodb
  mongodb --> mongoose

Installation

# pnpm
pnpm add mongoose-encrypt-fields
# npm
npm i mongoose-encrypt-fields
# yarn
yarn add mongoose-encrypt-fields

Usage

Basic usage

The plugin provides the EncryptedString SchemaType. To encrypt and decrypt, import and use this SchemaType.

import { Schema as MongooseSchema } from 'mongoose'
import { EncryptedString } from 'mongoose-encrypt-fields'
import { Schema } from 'mongoose' // Also accessible as Schema.Types.EncryptedString

Specify the field's type as EncryptedString. If the original type is not String, specify the original type in the originalType field.

Non-string fields are encrypted and decrypted using EJSON.stringify() and EJSON.parse() with { relaxed: true }. For more information, check the MongoDB Extended JSON format.

This behavior is the same as the PyMongo's json_util.

@Schema()
export class User {
  @Prop(EncryptedString) // String
  uniqueId!: string

  @Prop({ type: EncryptedString, originalType: [Number] }) // non-String
  coordinates!: number[]
}

You can also use it without any restrictions in SubDocuments.

@Schema()
export class UserSubDocument {
  @Prop(EncryptedString)
  uniqueId!: string
}

@Schema()
export class Review {
  @Prop(UserSubDocument) // subDocument
  subUser!: UserSubDocument

  @Prop([UserSubDocument]) // subDocument array
  subUsers!: UserSubDocument[]
}

You also need to inject the encryption functions into the SchemaType using EncryptedString.setEncryptionFunctions(). (This only needs to be called once in the code.)

However, if you apply the plugin described later, this part can be omitted.

• decrypt: Function to decrypt an encrypted string to plain text
• encrypt: Function to encrypt plain text to an encrypted string
• isEncrypted: Function to determine if a string is encrypted

const myEncrypt = (value: string): string => {
  // logic
}
const myDecrypt = (value: string): string => {
  // logic
}
const myIsEncrypted = (value: string): boolean => {
  // logic
}

// Call can be omitted when using the plugin
EncryptedString.setEncryptionFunctions({ encrypt: myEncrypt, decrypt: myDecrypt, isEncrypted: myIsEncrypted })

Most of the features will work even if you only use the SchemaType. However, decryption will not work if you use lean.

Applying the Plugin (for lean)

To decrypt properly in lean, you need to register the mongooseFieldEncryption plugin to the schema.

To apply the plugin to a schema, call the .plugin() method on the desired schema and add the encryption functions to the options.

import { Prop, Schema, SchemaFactory, MongooseModule } from '@nestjs/mongoose'
import { mongooseFieldEncryption } from '@pup/mongoose-encrypt-fields'

@Schema()
export class User {
  @Prop(EncryptedString)
  uniqueId!: string
}

export const UserSchema = SchemaFactory.createForClass(User)

export const UserModelModule = MongooseModule.forFeatureAsync([
  {
    name: User.name,
    useFactory: async () => {
      UserSchema.plugin(mongooseFieldEncryption, {
        encrypt: myEncrypt,
        decrypt: myDecrypt,
        isEncrypted: myIsEncrypted,
      })
      return UserSchema
    },
  },
])

Encrypted documents can be stored anywhere, so you can use the global plugin feature to register the plugin to all schemas at once.

MongooseModule.forRootAsync({
  useFactory: async () => {
    // Apply globally to support lean decryption in all schemas.
    // Prevent duplicate plugin registration with deduplicate option
    mongoose.plugin(mongooseFieldEncryption, {
      encrypt: myEncrypt,
      decrypt: myDecrypt,
      isEncrypted: myIsEncrypted,
      deduplicate: true,
    })
    ...
  },
})

Validation & Casting

The plugin also supports Validation and Casting for the OriginalType.

@Schema({ _id: false })
class Phone {
  @Prop({ required: true })
  phoneNumber!: string
}

export class Place {
  @Prop()
  placeId!: string

  @Prop({ type: EncryptedString, originalType: [Phone] })
  phone!: Phone[]
}

// 1. Validation error occurs since phoneNumber is a required field.
await placeModel.create({ placeId: 'placeId', phone: [{}] })

// 2. Document saved
await placeModel.create({ placeId: 'placeId', phone: [{ phoneNumber: 1234 }] })

Validation and Casting are also supported in Filter and Update queries.

// 1. Validation error occurs
await placeModel.findOne({ phone: [{}] })

// 2. No error
await placeModel.findOne({ phone: [{ phoneNumber: 1234 }] })

// 3. Validation error occurs
await placeModel.updateOne({ placeId: 'placeId' }, { $set: { phone: [{}] } })

// 4. No error
await placeModel.updateOne({ placeId: 'placeId' }, { $set: { phone: [{ phoneNumber: 1234 }] } })

Discriminator

Mongoose's discriminator feature is also supported. The usage is the same as the basic usage.

@Schema({ _id: false })
export class Location {
  @Prop({ required: true })
  type!: string

  @Prop({ required: true, type: EncryptedString, originalType: [Number] })
  coordinates!: number[]
}

@Schema({ _id: false })
export class LocationWithoutEncryption extends Location {
  @Prop([Number])
  coordinates!: number[]
}

@Schema()
export class GPSCheckIn implements CheckIn {
  type!: string

  @Prop(Location)
  location!: Location
}

@Schema()
export class PlaceCheckIn implements CheckIn {
  type!: string

  @Prop(LocationWithoutEncryption)
  location!: LocationWithoutEncryption
}

@Schema({ discriminatorKey: 'type' })
export class CheckIn {
  @Prop()
  type!: string
}
export const CheckInSchema = SchemaFactory.createForClass(CheckIn)

export const CheckInModelModule = MongooseModule.forFeatureAsync([
  {
    name: CheckIn.name,
    useFactory: async () => {
      return CheckInSchema
    },
    discriminators: [
      { value: CheckInType.GPS, name: GPSCheckIn.name, schema: GPSCheckInSchema },
      { value: CheckInType.PLACE, name: PlaceCheckIn.name, schema: PlaceCheckInSchema },
    ],
  },
])

However, if you want to use the discriminator schema in a subDocument, you must specify the type of the corresponding field as a schema type.

This is because Mongoose requires a schema to know the discriminator information.

export class Review {
  // To use discriminator in subDocument, type must be specified as schema
  @Prop({ type: CheckInSchema })
  checkIn?: CheckIn
}

Aggregate Not Supported

Encryption for Aggregate is not supported.

License

mongoose-encrypt-fields in released under the MIT license.

mongoose-encrypt-fields
Copyright 2024-present NAVER Corp.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.