@flowerforce/flowerbase 1.7.6-beta.0 → 1.7.6-beta.2

package/src/utils/__tests__/mongodbCSFLE.test.ts

@@ -0,0 +1,105 @@
+import { UUID } from 'mongodb'
+import type { EncryptionSchemas } from '../../features/encryption/interface'
+import { buildSchemaMap } from '../initializer/mongodbCSFLE'
+
+describe('buildSchemaMap', () => {
+  const genericSchemas: EncryptionSchemas = {
+    'appDb.records': {
+      bsonType: 'object',
+      encryptMetadata: {
+        keyAlias: 'root-key'
+      },
+      properties: {
+        publicText: {
+          encrypt: {
+            bsonType: 'string',
+            algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Random'
+          }
+        },
+        protectedText: {
+          encrypt: {
+            bsonType: 'string',
+            algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic',
+            keyAlias: 'root-key'
+          }
+        },
+        nestedObject: {
+          bsonType: 'object',
+          encryptMetadata: { keyAlias: 'nested-key' },
+          properties: {
+            deepObject: {
+              bsonType: 'object',
+              properties: {
+                deepSecret: {
+                  encrypt: {
+                    bsonType: 'string',
+                    algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Random',
+                    keyAlias: 'deep-key'
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  it('resolves keyAlias to keyId for root and nested schemas', () => {
+    const rootKeyId = new UUID()
+    const nestedKeyId = new UUID()
+    const deepKeyId = new UUID()
+
+    const schemaMap = buildSchemaMap(genericSchemas, [
+      { dataKeyAlias: 'root-key', dataKeyId: rootKeyId },
+      { dataKeyAlias: 'nested-key', dataKeyId: nestedKeyId },
+      { dataKeyAlias: 'deep-key', dataKeyId: deepKeyId }
+    ])
+
+    expect(schemaMap['appDb.records']).toEqual({
+      bsonType: 'object',
+      encryptMetadata: { keyId: [rootKeyId] },
+      properties: {
+        publicText: {
+          encrypt: {
+            bsonType: 'string',
+            algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Random'
+          }
+        },
+        protectedText: {
+          encrypt: {
+            bsonType: 'string',
+            algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic',
+            keyId: [rootKeyId]
+          }
+        },
+        nestedObject: {
+          bsonType: 'object',
+          encryptMetadata: { keyId: [nestedKeyId] },
+          properties: {
+            deepObject: {
+              bsonType: 'object',
+              properties: {
+                deepSecret: {
+                  encrypt: {
+                    bsonType: 'string',
+                    algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Random',
+                    keyId: [deepKeyId]
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    })
+  })
+
+  it('throws when nested keyAlias cannot be resolved', () => {
+    const rootKeyId = new UUID()
+
+    expect(() =>
+      buildSchemaMap(genericSchemas, [{ dataKeyAlias: 'root-key', dataKeyId: rootKeyId }])
+    ).toThrow('Key with alias deep-key could not be found in the Key Vault.')
+  })
+})

package/src/utils/index.ts

@@ -1,5 +1,16 @@
-import fs from 'fs'
+import fs from 'node:fs'
+import path from 'node:path'
 
 export const readFileContent = (filePath: string) => fs.readFileSync(filePath, 'utf-8')
 export const readJsonContent = (filePath: string) =>
   JSON.parse(readFileContent(filePath)) as unknown
+
+export const recursivelyCollectFiles = (dir: string): string[] => {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      return recursivelyCollectFiles(fullPath)
+    }
+    return entry.isFile() ? [fullPath] : []
+  })
+}

package/src/utils/initializer/mongodbCSFLE.ts

@@ -0,0 +1,224 @@
+import {
+  ClientEncryption,
+  MongoClient,
+  UUID,
+  Binary,
+  type Document,
+  type AWSEncryptionKeyOptions,
+  type AWSKMSProviderConfiguration,
+  type AzureEncryptionKeyOptions,
+  type AzureKMSProviderConfiguration,
+  type GCPKMSProviderConfiguration,
+  type GCPEncryptionKeyOptions,
+  type KMIPKMSProviderConfiguration,
+  type KMIPEncryptionKeyOptions,
+  type LocalKMSProviderConfiguration,
+  type AutoEncryptionExtraOptions,
+  type KMSProviders,
+  type AutoEncryptionOptions,
+} from "mongodb";
+import { EncryptionSchemaProperty, MappedEncryptionSchema, MappedEncryptionSchemaProperty, type EncryptionSchemas } from "../../features/encryption/interface";
+import { DEFAULT_CONFIG } from "../../constants";
+
+type KMSProviderConfig =
+  | {
+    /**
+     * The alias of the key. It must be referenced in the schema map
+     * to select which key to use for encryption.
+     */
+    keyAlias: string
+    /**
+     * KMS Provider name.
+     */
+    provider: "aws"
+    /**
+     * KMS Provider specific authorization configuration.
+     */
+    config: AWSKMSProviderConfiguration
+    /**
+     * Configuration of the master key.
+     */
+    masterKey: AWSEncryptionKeyOptions
+  } | {
+    keyAlias: string
+    provider: "azure"
+    config: AzureKMSProviderConfiguration,
+    masterKey: AzureEncryptionKeyOptions
+  } | {
+    keyAlias: string
+    provider: "gcp"
+    config: GCPKMSProviderConfiguration,
+    masterKey: GCPEncryptionKeyOptions
+  } | {
+    keyAlias: string
+    provider: "kmip"
+    config: KMIPKMSProviderConfiguration,
+    masterKey: KMIPEncryptionKeyOptions
+  } | {
+    keyAlias: string
+    provider: "local"
+    config: LocalKMSProviderConfiguration,
+  }
+
+export type MongoDbEncryptionConfig = {
+  kmsProviders: KMSProviderConfig[],
+  /**
+   * The Key Vault database name
+   * @default encryption
+   */
+  keyVaultDb?: string
+  /**
+ * The Key Vault database collection
+ * @default __keyVault
+ */
+  keyVaultCollection?: string
+  extraOptions?: AutoEncryptionExtraOptions
+}
+
+/**
+ * @internal
+ */
+type RequiredConfig = Required<Omit<MongoDbEncryptionConfig, "extraOptions">>
+
+type DataKey = { dataKeyId: UUID, dataKeyAlias: string }
+
+async function ensureUniqueKeyAltNameIndex(db: ReturnType<MongoClient['db']>, config: RequiredConfig): Promise<void> {
+  await db.collection(config.keyVaultCollection).createIndex(
+    { keyAltNames: 1 },
+    {
+      unique: true,
+      partialFilterExpression: { keyAltNames: { $exists: true } },
+    }
+  );
+}
+
+/**
+ * Ensure provided KMS Providers DEK keys exist in the key vault. If not, they are created.
+ */
+async function ensureDataEncryptionKeys(
+  clientEncryption: ClientEncryption,
+  keyVaultDb: ReturnType<MongoClient['db']>,
+  config: RequiredConfig
+): Promise<DataKey[]> {
+  const keys: DataKey[] = []
+
+  for (const kmsProvider of config.kmsProviders) {
+    const existingKey = await keyVaultDb.collection(config.keyVaultCollection).findOne({
+      keyAltNames: kmsProvider.keyAlias,
+    });
+
+    if (existingKey?._id instanceof Binary) {
+      keys.push({ dataKeyId: existingKey._id, dataKeyAlias: kmsProvider.keyAlias })
+      continue
+    }
+
+    const dataKeyId = await clientEncryption.createDataKey(kmsProvider.provider, {
+      masterKey: "masterKey" in kmsProvider ? kmsProvider.masterKey : undefined,
+      keyAltNames: [kmsProvider.keyAlias],
+    });
+    console.log(`[MongoDB Encryption] Created new key with alias ${kmsProvider.keyAlias}`)
+    keys.push({ dataKeyId, dataKeyAlias: kmsProvider.keyAlias })
+  }
+
+  return keys
+}
+
+/**
+ * Recursively resolve key aliases in an encryption schema to their corresponding key IDs.
+ */
+const resolveKeyAliases = (schema: EncryptionSchemaProperty, dataKeys: DataKey[]): MappedEncryptionSchemaProperty => {
+  if ("encrypt" in schema) {
+    if (!schema.encrypt.keyAlias) {
+      return schema
+    }
+    const keyId = dataKeys.find(k => k.dataKeyAlias === schema.encrypt.keyAlias)?.dataKeyId
+    if (!keyId) {
+      throw new Error(`Key with alias ${schema.encrypt.keyAlias} could not be found in the Key Vault.`)
+    }
+    return {
+      encrypt: {
+        bsonType: schema.encrypt.bsonType,
+        algorithm: schema.encrypt.algorithm,
+        keyId: [keyId]
+      }
+    }
+  }
+  const mappedSchema: MappedEncryptionSchema = {
+    bsonType: "object",
+    properties: Object.entries(schema.properties).reduce((acc, [property, config]) => {
+      acc[property] = resolveKeyAliases(config, dataKeys)
+      return acc
+    }, {} as Record<string, MappedEncryptionSchemaProperty>)
+  }
+
+  if (schema.encryptMetadata) {
+    const keyId = dataKeys.find(k => k.dataKeyAlias === schema.encryptMetadata!.keyAlias)?.dataKeyId
+    if (!keyId) {
+      throw new Error(`Key with alias ${schema.encryptMetadata.keyAlias} could not be found in the Key Vault.`)
+    }
+    mappedSchema.encryptMetadata = { keyId: [keyId] }
+  }
+
+  return mappedSchema
+}
+
+export const buildSchemaMap = (schemas: EncryptionSchemas, dataKeys: DataKey[]) => {
+  return Object.entries(schemas).reduce((acc, [key, schema]) => {
+    acc[key] = resolveKeyAliases(schema, dataKeys)
+    return acc
+  }, {} as Record<string, Document>)
+}
+
+/**
+ * Setup MongoDB Client-Side Field Level Encryption (CSFLE).
+ * @see https://www.mongodb.com/docs/manual/core/csfle
+ */
+export const setupMongoDbCSFLE = async (
+  config: MongoDbEncryptionConfig & { mongodbUrl: string; schemas?: EncryptionSchemas }
+): Promise<AutoEncryptionOptions> => {
+  if (config.kmsProviders.length === 0) {
+    throw new Error('At least one KMS Provider is required when using MongoDB encryption')
+  }
+
+  const requiredConfig: RequiredConfig = {
+    kmsProviders: config.kmsProviders,
+    keyVaultDb: config.keyVaultDb ?? DEFAULT_CONFIG.MONGODB_ENCRYPTION_CONFIG.keyVaultDb,
+    keyVaultCollection: config.keyVaultDb ?? DEFAULT_CONFIG.MONGODB_ENCRYPTION_CONFIG.keyVaultCollection,
+  }
+
+  const kmsProviders = requiredConfig.kmsProviders.reduce(
+    (acc, { provider, config }) => ({ ...acc, [provider]: config }),
+    {} as KMSProviders
+  )
+
+  const keyVaultNamespace = `${requiredConfig.keyVaultDb}.${requiredConfig.keyVaultCollection}`
+  const keyVaultClient = new MongoClient(config.mongodbUrl, {
+    maxPoolSize: 1,
+    autoEncryption: {
+      keyVaultNamespace,
+      kmsProviders,
+      extraOptions: config.extraOptions
+    }
+  });
+
+  await keyVaultClient.connect();
+
+  const keyVaultDb = keyVaultClient.db(requiredConfig.keyVaultDb);
+  await ensureUniqueKeyAltNameIndex(keyVaultDb, requiredConfig)
+
+  const clientEncryption = new ClientEncryption(keyVaultClient, {
+    keyVaultNamespace,
+    kmsProviders,
+  });
+
+  const dataKeys = await ensureDataEncryptionKeys(clientEncryption, keyVaultDb, requiredConfig)
+
+  await keyVaultClient.close()
+
+  return {
+    keyVaultNamespace,
+    kmsProviders,
+    schemaMap: config.schemas ? buildSchemaMap(config.schemas, dataKeys) : undefined,
+    extraOptions: config.extraOptions
+  }
+}

package/src/utils/initializer/registerPlugins.ts

@@ -1,5 +1,5 @@
 import cors from '@fastify/cors'
-import fastifyMongodb from '@fastify/mongodb'
+import fastifyMongodb, { FastifyMongodbOptions } from '@fastify/mongodb'
 import { FastifyInstance } from 'fastify'
 import fastifyRawBody from 'fastify-raw-body'
 import { CorsConfig } from '../../'
@@ -10,7 +10,9 @@ import { customFunctionController } from '../../auth/providers/custom-function/c
 import { localUserPassController } from '../../auth/providers/local-userpass/controller'
 import { API_VERSION, DEFAULT_CONFIG } from '../../constants'
 import { Functions } from '../../features/functions/interface'
+import { EncryptionSchemas } from '../../features/encryption/interface'
 import monitoringPlugin from '../../monitoring/plugin'
+import { setupMongoDbCSFLE, MongoDbEncryptionConfig } from './mongodbCSFLE'
 
 type RegisterFunction = FastifyInstance['register']
 type RegisterParameters = Parameters<RegisterFunction>
@@ -21,6 +23,8 @@ type RegisterPluginsParams = {
   jwtSecret: string
   functionsList: Functions
   corsConfig?: CorsConfig
+  encryptionSchemas?: EncryptionSchemas
+  mongodbEncryptionConfig?: MongoDbEncryptionConfig
 }
 
 type RegisterConfig = {
@@ -41,14 +45,18 @@ export const registerPlugins = async ({
   mongodbUrl,
   jwtSecret,
   functionsList,
-  corsConfig
+  corsConfig,
+  mongodbEncryptionConfig,
+  encryptionSchemas
 }: RegisterPluginsParams) => {
   try {
     const registersConfig = await getRegisterConfig({
       mongodbUrl,
       jwtSecret,
       corsConfig,
-      functionsList
+      functionsList,
+      mongodbEncryptionConfig,
+      encryptionSchemas
     })
 
     registersConfig.forEach(({ plugin, options, pluginName }) => {
@@ -75,15 +83,23 @@ export const registerPlugins = async ({
 const getRegisterConfig = async ({
   mongodbUrl,
   jwtSecret,
-  corsConfig
-}: Pick<RegisterPluginsParams, 'jwtSecret' | 'mongodbUrl' | 'functionsList' | 'corsConfig'>): Promise<
-  RegisterConfig[]
-> => {
+  corsConfig,
+  encryptionSchemas,
+  mongodbEncryptionConfig,
+}: Omit<RegisterPluginsParams, "register">): Promise<RegisterConfig[]> => {
   const corsOptions = corsConfig ?? {
     origin: '*',
     methods: ['POST', 'GET']
   }
 
+  const autoEncryption = mongodbEncryptionConfig
+    ? await setupMongoDbCSFLE({
+      mongodbUrl,
+      schemas: encryptionSchemas,
+      ...mongodbEncryptionConfig
+    })
+    : undefined
+
   const baseConfig = [
     {
       pluginName: 'cors',
@@ -94,9 +110,28 @@ const getRegisterConfig = async ({
       pluginName: 'fastifyMongodb',
       plugin: fastifyMongodb,
       options: {
+        url: mongodbUrl,
         forceClose: true,
-        url: mongodbUrl
-      }
+        autoEncryption
+      } satisfies FastifyMongodbOptions
+    },
+    /**
+     * When auto-encryption is active, add another MongoDB client with bypass for change streams.
+     * The $changeStream operator does not support automatic encryption, only decryption.
+     * @see https://www.mongodb.com/docs/manual/core/csfle/reference/supported-operations
+     */
+    autoEncryption && {
+      pluginName: 'fastifyMongodb',
+      plugin: fastifyMongodb,
+      options: {
+        name: "changestream",
+        url: mongodbUrl,
+        forceClose: true,
+        autoEncryption: {
+          ...autoEncryption,
+          bypassAutoEncryption: true
+        }
+      } satisfies FastifyMongodbOptions
     },
     {
       pluginName: 'jwtAuthPlugin',
@@ -153,5 +188,5 @@ const getRegisterConfig = async ({
     } as RegisterConfig)
   }
 
-  return baseConfig
+  return baseConfig.filter(Boolean)
 }